内容
# contextd
**AI 编码代理上下文的构建系统**
contextd 将工作区知识、软件包、合约和策略编译成适用于 Claude、Codex、Cursor 和 MCP 的确定性上下文工件。
## 入门指南
> **越南语：** [入门指南（越南语）](https://philngt.github.io/contextd/onboarding/index.html) · [安装指南（越南语）](https://philngt.github.io/contextd/onboarding/install.html)
> **英语：** [入门指南（英文）](https://philngt.github.io/contextd/onboarding/index.en.html) · [安装指南（英文）](https://philngt.github.io/contextd/onboarding/install.en.html)
## 理论基础（不可妥协）
1. **代理上下文是一种构建工件**
团队知识是源材料；`contextd context` 编译由代理适配器消耗的任务特定工件。
2. **工作区隔离是强制性的**
检索和上下文生成的作用域限定为当前代码库的活动工作区。
3. **软件包是认知支架，而不仅仅是模板**
软件包是可重用的推理模块，用于构建任务框架、验证和执行质量。
4. **运行时中立的核心，适配器特定的表面**
`.contextd/config.json` 和 CLI 是规范的。Claude Code 斜杠命令、Codex 技能、Cursor 规则和平凡的软件包通过适配器使用相同的 workspace 知识。
5. **确定性知识优先级**
合约 > 平台模式 > 项目文档 > 领域知识。
## 适用对象
- 跨多个项目/公司使用 AI 编码代理并需要严格的工作区级隔离的团队。
- 想要可重用模式和运行时适配器以使代理输出一致的工程师/技术负责人。
- 需要结构化知识以便代理可以执行的产品/运营/领域团队。
- 也适用于想要可重复的 AI 辅助工作流的单独构建者和平台/文档所有者。
如果您只需要一个没有代理工作流的静态人类可读 wiki，则不适合。
## 项目状态
该项目在**尽力而为**的基础上维护。
- 欢迎社区贡献
- 如果维护人员的能力发生变化，项目可能会进入维护模式或存档状态
使用权根据存储库许可证（[MIT](LICENSE)）提供，并按**“原样”**提供，不提供任何保证。
## 支持与兼容性
| 功能 | 状态 |
|---|---|
| Claude Code 斜杠命令 | 稳定 |
| Claude Code 子代理 | 稳定 |
| 工作区/软件包 Markdown 引擎 | 稳定 |
| CLI：解析/查找/打包 | 可用（从 GitHub Releases 或源代码 checkout） |
| CLI：确定性任务上下文 | 可用（`contextd context`） |
| CLI：诊断和选择解释 | 可用（`contextd doctor`，`contextd explain`） |
| CLI：管理和评估 | 可用（`contextd policy-check`，`contextd pack-validate`，`contextd eval --golden`） |
| 普通 Markdown 软件包导出 | 可用 |
| Codex 技能/插件导出 | 可用 |
| Cursor 规则导出 | 可用 |
| MCP stdio 工具适配器 | 可用（`contextd mcp-server`） |
**系统需求**
- macOS/Linux：需要 `bash`。
- Windows：推荐使用 PowerShell + Git Bash 或 WSL 执行 shell 安装程序。
- 需要写入 `~/.contextd/` 的权限用于全局配置。Claude Code 适配器仍写入 `~/.claude/`。
- 发布二进制安装程序前提条件：macOS/Linux 上的 `curl` 或 `wget`；Windows 上的 PowerShell `Invoke-WebRequest`。
- 源代码/开发人员安装需要 Python 3 和 Git。
## 思维模型：构建代理上下文
contextd 是用于代理输入的本地构建系统：
1. **CLI 核心**：`contextd resolve`，`contextd doctor`，`contextd find`，`contextd bundle`
2. **任务上下文工件**：`contextd context "task" --format json`，使用 `contextd explain "task"` 进行选择跟踪
3. **清单索引**：`.contextd/manifest.json`
4. **运行时导出/适配器**：普通 Markdown，Codex 技能/插件，Cursor 规则，Claude Code 工件，MCP stdio 工具
现有的 `.claude/commands` 和 `.claude/agents` 在迁移窗口期间仍受支持，但 `.contextd/config.json` 是规范的项目配置。
有关更深入的模型，请参见 [docs/build-system-model.md](docs/build-system-model.md)。它解释了源输入、构建图、工件生命周期、确定性边界和常见故障模式。
## 非目标
- contextd 不是一个向量数据库。
- MCP 是可选的。contextd 不需要 MCP SDK、远程 MCP 服务器或编排运行时。
- contextd 不替换编码代理；它为代理构建范围可审计的输入。
## 存储库模型
contextd = **构建引擎**（共享）+ **N 个工作区**（源知识）+ **适配器输出**。
```text
contextd/
├── agents/ ← 引擎 — 系统、管道、编码规则（与工作区无关）
├── templates/ ← 引擎 — 新工作区和文档的模板
├── .contextd/ ← 引擎 — 清单/配置/上下文运行时命名空间
├── .claude/ ← 适配器 — Claude Code 斜杠命令
└── workspaces/ ← N 个工作区，每个工作区都有平台/领域/项目/... 数据
└── {name}/...
# 活动工作区按代码库存储在 <project>/.contextd/config.json 中。
```
### 兼容性：旧适配器
旧的 `<project>/.claude/wiki.json` 和 `<project>/.Codex/wiki.json` 在迁移窗口期间作为适配器读取。它们不是事实的来源。
## 软件包（特定于堆栈的知识）
软件包是引擎和工作区之间的堆栈/用例知识层：
- 引擎：共享的、与堆栈无关的规则和管道。
- 软件包：特定于堆栈的规则/模式/合约（web-api、事件驱动、前端、代理、产品、...）。
- 工作区：公司/项目特定的领域和实现知识。
通过以下方式启用软件包：
- 工作区默认值：`workspaces/{ws}/workspace.md` → `## 软件包`
- 按代码库覆盖：`<cwd>/.contextd/config.json` → `packs`（替换语义）
有关完整目录，请参见 [packs/README.md](packs/README.md)。
## 引擎和工作区参考
- 引擎文件夹：[agents/](agents/)，[templates/](templates/)，[.claude/commands/](.claude/commands/)
- 工作区结构和覆盖：[workspaces/README.md](workspaces/README.md)
## 如何使用
### 首次设置（运行一次）
**GitHub Release assets 中的简短一行命令**（每个发布标签生成）：
```bash
curl -fsSL https://github.com/philngt/contextd/releases/latest/download/install.sh | sh
```
PowerShell（Windows）：
```powershell
iwr https://github.com/philngt/contextd/releases/latest/download/install.ps1 -UseBasicParsing | iex
```
这些安装程序从 GitHub Releases 安装预构建的 `contextd` 二进制文件。用户无需在本地构建 CLI。
### 安全安装（在运行前验证 SHA256）
```bash
TAG="vX.Y.Z"
BASE_URL="https://github.com/philngt/contextd/releases/download/${TAG}"
curl -fL -o install.sh "${BASE_URL}/install.sh"
curl -fL -o SHA256SUMS.txt "${BASE_URL}/SHA256SUMS.txt"
grep ' install.sh$' SHA256SUMS.txt | shasum -a 256 -c -
sh install.sh
```
PowerShell（Windows）：
```powershell
$Tag = "vX.Y.Z"
$BaseUrl = "https://github.com/philngt/contextd/releases/download/$Tag"
Invoke-WebRequest "$BaseUrl/install.ps1" -OutFile "install.ps1"
Invoke-WebRequest "$BaseUrl/SHA256SUMS.txt" -OutFile "SHA256SUMS.txt"
$expected = (Select-String -Path .\SHA256SUMS.txt -Pattern ' install.ps1$').Line.Split(' ')[0].Trim()
$actual = (Get-FileHash .\install.ps1 -Algorithm SHA256).Hash.ToLower()
if ($actual -ne $expected.ToLower()) { throw "SHA256 mismatch for install.ps1" }
.\install.ps1
```
开发人员/源代码 checkout 流程（用于编辑此存储库或从 checkout 安装 Claude 适配器）：
```bash
pip install -e .
bash scripts/install-to-claude.sh --knowledge-root ~/contextd --default-workspace default
bash scripts/install-to-claude.sh --dry-run
bash scripts/install-to-claude.sh --force
```
如果您的工作区位于单独的团队存储库中：
```bash
bash scripts/install-to-claude.sh --knowledge-root ~/company-wiki --default-workspace shared
```
### 迁移现有代码库配置
```bash
contextd migrate-config --dry-run
contextd migrate-config
```
这会从现有的 `.claude/wiki.json` 或 `.Codex/wiki.json` 创建 `<project>/.contextd/config.json`。旧文件可能仍保留以兼容。
### 启动会话（在代码库内）
```text
/list-workspaces
/switch-workspace {name}
```
在请求代理工作之前，请验证运行时：
```bash
contextd resolve --format json
contextd doctor --format text
```
### 接收任务时
```text
/use-contextd "添加 Kafka 消费者..."
```
或使用运行时中立的 CLI：
```bash
contextd context "添加 Kafka 消费者..." --format json
contextd explain "添加 Kafka 消费者..." --format text
contextd contract-path citation-format
```
`contextd context` 发出规范的 JSON 工件。`contextd explain` 显示选择或丢弃文档的原因，包括差距、警告、源哈希和轻量级预算报告。
有关预算语义、安全防护行为和滚动记分卡，请参见 [docs/context-quality.md](docs/context-quality.md)。
### 生产治理循环
在将 contextd 集成到团队工作流中或更改软件包/工作区知识后，请使用此循环：
```bash
contextd doctor --format json
contextd pack-validate --all --format json
contextd context "调试上下文质量" --format json --no-materialize
contextd explain "调试上下文质量" --format json
contextd policy-check "调试上下文质量" --format json
contextd eval --golden --workspace default --format json
```
- [docs/governance.md](docs/governance.md)：选定上下文上的策略即代码。
- [docs/pack-validation.md](docs/pack-validation.md)：软件包 API 和检索映射验证。
- [docs/evaluation.md](docs/evaluation.md)：上下文选择质量的黄金任务评估。
- [docs/build-system-model.md](docs/build-system-model.md)：更深入的产品和工件模型。
### MCP 适配器
将 contextd 运行为本地 stdio MCP 工具服务器：
```bash
contextd mcp-server --knowledge-root ~/contextd --workspace default
contextd mcp-config --client codex --knowledge-root ~/contextd --workspace default
```
有关 Claude、Cursor、Codex 代码段、安全说明、工具、资源和提示，请参见 [docs/mcp.md](docs/mcp.md)。
### 编码后
```text
/update-contextd
/rebase-contextd
```
### 创建新工作区
```text
/new-workspace {name}
```
## Codex 用法
contextd 也可与 OpenAI Codex CLI 一起使用，通过导出的技能或 MCP 适配器。
1. 使用上述发布二进制安装程序安装 `contextd` CLI。对于源代码 checkout 开发，仅需：
```bash
pip install -e .
```
2. 从 CLI 安装 Codex 技能：
```bash
contextd export --runtime codex-plugin --install
```
如果您正在使用此源代码 checkout，辅助脚本等效：
```bash
bash scripts/setup-codex-skills.sh
```
3. 在具有 `.contextd/config.json` 的任何项目中，Codex 现在可以使用 contextd：
```bash
codex 'Run contextd resolve and find the relevant contract for this task'
```
## 部署 GitHub Pages
工作流：[deploy-pages.yml](.github/workflows/deploy-pages.yml)
- 触发：
- `push` 到 `main` 时，`onboarding/**` 发生变化
- 手动 `workflow_dispatch`
- 构建流程：
1. `bash scripts/package-release.sh`
2. 收集 `onboarding/` 和 `release/`
3. 部署到 `github-pages`
## 发布
工作流：[release.yml](.github/workflows/release.yml)
- 触发：
- semver 标签推送 `v*.*.*`
- 手动 `workflow_dispatch`
- 流程：打包发布工件，然后发布 GitHub Release 资产。
## 故障排除
- 斜杠命令不可见：重新运行 `bash scripts/install-to-claude.sh` 并重启 Claude Code。
- 缺失 `.contextd/config.json`：运行 `contextd migrate-config`、`/contextd-setup` 或 `/switch-workspace`。
- 错误的工作区上下文：验证 `<cwd>/.contextd/config.json` 中的 `workspace`；在迁移期间，旧适配器优先级较低。
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
[MIT](LICENSE)
