内容
# 代理状态开发者
代码级上下文和审计叠加层，用于代理编写的代码。
ASD 为每个函数提供决策账本、影响声明和调用图——所有这些都可由编写代码的编码代理查询，并且所有这些都检查到 git 中，以便它们随每个克隆一起旅行。
**作为套件的一部分：**ASD（每个开发者的代码上下文）与 **[CTXone](https://github.com/ctxone/ctxone)**（共享团队内存）配对。安装其中一个即可提供另一个 - 请参阅 [与 CTXone 配对](#与-ctxone配对)。
## 安装
### macOS / Linux — Homebrew（推荐）
```bash
brew tap agentstatelabs/agentstatedeveloper
brew trust agentstatelabs/agentstatedeveloper # 一次性，第三方 tap 信任
brew install asd
```
安装 `asd`、`asd-mcp` 和 `asd-serve`。通过 `brew upgrade asd` 升级。
> 最近的 Homebrew 需要明确的 `brew trust` 来信任第三方 tap。如果您跳过信任步骤，您将在 `brew update` 时看到 `Warning: Skipping … because it is not trusted` — 安装仍将成功，直到更新被静默跳过。
### macOS / Linux — 一行安装
```bash
curl -fsSL https://raw.githubusercontent.com/agentstatelabs/AgentStateDeveloper/main/install.sh | sh
```
将三个二进制文件放入 `~/.local/bin`。可选覆盖：`ASD_VERSION=v1.2.0`，`INSTALL_DIR=/usr/local/bin`。
### Windows — PowerShell
```powershell
iwr https://raw.githubusercontent.com/agentstatelabs/AgentStateDeveloper/main/install.ps1 | iex
```
安装 `asd.exe`、`asd-mcp.exe` 和 `asd-serve.exe` 到 `%LOCALAPPDATA%\asd\bin` 并将其添加到您的用户 `PATH`。安装后打开一个新的 PowerShell 窗口，使新的 PATH 生效。
> Windows 二进制文件是为 `x86_64-pc-windows-msvc` 构建的。ARM64 Windows 暂时不是发布目标 - x86_64 二进制文件在过渡期内在 Windows ARM 模拟下运行。
### 从源代码（需要 Rust 工具链）
```bash
cargo install --path crates/agentstatedeveloper-cli # 安装 asd
cargo install --path crates/agentstatedeveloper-mcp # 安装 asd-mcp + asd-serve
```
> **注意：** crates.io 上的 crate 名称 `asd` 被一个无关的 diff 工具占用。使用上述命令从源代码安装。
### 卸载
```bash
curl -fsSL https://raw.githubusercontent.com/agentstatelabs/AgentStateDeveloper/main/uninstall.sh | sh
# 或：
brew uninstall asd
```
## 功能
| 原始功能 | 您获得的内容 |
|---|---|
| **决策账本** | 将决策、危险、原理和约束附加到任何符号上。记录保留符号重命名。批准、拒绝或撤回。 |
| **影响声明** | 17 类别（`io.fs.read`、`io.net.out`、`io.db.write` 等）。每个符号声明，影响在调用图上传递。 |
| **语义索引** | 每个函数、方法和类由 tree-sitter 解析。9 种语言：Python、TypeScript、Rust、Go、Java、C#、Ruby、Kotlin、Swift。 |
| **调用图** | 模块内和跨模块的边。影响在调用图上传递。 |
| **策略门** | 文件支持的 JSON 规则：允许、拒绝或需要批准每个操作和执行者类型。 |
| **批准** | 批准、拒绝或撤回账本记录。完整的批准工作流程。 |
| **审计事件流** | 每个账本突变和策略评估的哈希链接 JSONL 日志。 |
| **Git 原生侧车** | 提交的、紧凑的账本记录子集（决策、危险、配方、映射、分类、跟进、代理思考）存储在 `.asd/conclusions/*.jsonl` - 检查到 git 中，与每个克隆一起旅行。千字节，而不是兆字节。 |
## 与 CTXone 配对
ASD 和 **[CTXone](https://github.com/ctxone/ctxone)** 作为套件构建：
- **ASD** — 每个开发者的 **代码上下文**：您面前的代码的决策账本、影响声明、调用图和影响分析。
- **CTXone** — **团队层**：共享的决策、计划和内存，适用于整个团队。
每个产品都可以独立使用，但它们搭配使用效果更好：
- 安装其中一个 **提供设置另一个** - 一次性、可忽略的提示（可通过 `--no-nudge` 或 `ASD_NO_SUGGEST=1` 抑制）。
- 当两者都安装时，`asd skill` 还会安装一个 **组合套件技能**，教导代理联合工作流程：使用 ASD 获取代码特定信息（影响、不变性），并将您的决定记录到 CTXone 中，以便团队继承。
- `asd bootstrap` 提供安装 **两者**。
## 快速入门
```bash
# 克隆并构建
git clone https://github.com/agentstatelabs/AgentStateDeveloper.git
cd AgentStateDeveloper
cargo install --path crates/agentstatedeveloper-cli
cargo install --path crates/agentstatedeveloper-mcp
# 初始化您的项目
cd my-project
asd init
asd index .
# 读取符号
asd read payments.chargeCard
# 追加账本记录
asd ledger append payments.chargeCard \
--kind hazard \
--summary "fails silently above 10000 — caller must check return value" \
--author-kind human \
--author-id alice@example.com
# 在您的代理工具中注册 MCP 服务器
asd mcp install
# 导出已提交的侧车并提交
asd conclusions export
git add .asd/conclusions/
git commit -m "chore: sync ASD sidecar"
```
（`asd init` 预提交钩子会自动运行 `asd conclusions export`；上面的显式两步操作只是为了说明发生了什么。）
### MCP ↔ CLI 命名参考
ASD 有两个表面，具有两种命名约定：MCP 使用平面命名空间（`ledger_append`、`code_search`），以避免与其他 MCP 服务器冲突；CLI 嵌套（`asd ledger append`、`asd search`）。规范映射位于 [docs/mcp-cli-mapping.md](docs/mcp-cli-mapping.md)。两种形式都适用于 CLI - 熟悉旧 MCP 文档的代理可以输入 `asd ledger append` 或（通过 Plan D t-003 的 clap 别名）等效的 `asd code_search` / `asd callers_of` 等。
### 代理的简洁输出模式
`asd` 默认采用人类和结构化解析管道友好的详细 JSON 形状，但代理很少需要这些信息。
设置 `ASD_FORMAT=brief`（或逐个调用传递 `--brief`）以将 `read` / `callers` / `callees` 响应减少到仅承载字段（qname、file:line、signature、第一个文档行）。典型减少：60–80% 适用于这些命令。
建议代理在进程启动时执行一次：
```bash
export ASD_FORMAT=brief
```
适用于 CLI 和 MCP。启动的 `asd-mcp` 服务器从其父进程继承 `ASD_FORMAT=brief`，并通过相同的紧凑形状投影三个高容量读取工具（`code_read`、`code_search`、`references`）。
## 代理设置
ASD 通过几个层插入您的编码代理。最快的路径是让代理自行设置。
### 粘贴到您的代理（推荐）
```bash
asd bootstrap
```
打印一个短块，您可以将其粘贴到您已经在使用的任何代理中（Claude Code、Cursor、Codex、Gemini CLI 等）。然后，代理安装、索引并连接 ASD - 并提供设置 **CTXone**（团队层）的选项。
### 单个命令
| 命令 | 设置 |
|---|---|
| `asd mcp install` | 在每个检测到的代理的 MCP 配置中注册 `asd-mcp` stdio 服务器 - Claude Code、Claude Desktop、Cursor、Codex、Gemini CLI、Windsurf、Zed、VS Code、Cline、Kilo Code、Antigravity 等。重启工具以激活。 |
| `asd skill` | 将 ASD 的 **代理技能**（`SKILL.md`）安装到每个主机的技能目录中 - 教导代理 **何时** 使用 ASD。当存在 `ctx` CLI 时，还会安装组合 **ASD + CTXone** 套件技能。 |
| `asd mcp instructions` | 将托管的始终开启的使用块注入 `AGENTS.md` / `CLAUDE.md`（幂等 - 安全地重新运行）。 |
| `asd watch` | 监视存储库并在源代码更改时重新索引，以便索引永远不会静默漂移。 |
```bash
asd mcp status # 跨所有工具的注册状态
asd mcp install --tool cursor # 特定工具
asd mcp install --db /abs/db # 非默认数据库路径
asd mcp uninstall # 从所有工具中删除
asd skill --status # 已安装的内容，按主机
asd skill --dry-run # 预览而不写入
```
MCP 服务器读取 `ASD_DB`（由 `install` 在 env 块中设置），因此代理始终连接到正确的项目数据库。
## Git 原生侧车
ASD 有两个磁盘位置和一个 SQLite 命名空间。知道哪一个是哪个以避免惊喜：
| 位置 | 内容 | 跟踪到 git？ | 对什么具有权威性？ |
|----------|--------------|-----------------|---------------------|
| `.asd-state.db` | 实时 SQLite ASG（索引、调用图、全文搜索、完整账本、跟踪） | **否** （gitignored） | 运行时所有内容 |
| `.asd/conclusions/*.jsonl` | 紧凑的子集：决策、分类、映射、危险、配方、跟进、代理思考 | **是** | 新克隆体需要继承的内容 |
| `.asd/v1/` （旧版） | 旧的详细镜像 - 被 `.asd/conclusions/` 取代 | **否** （gitignored） | 遗留；`asd sync` / `asd hydrate` 仍然为本地调试写入/读取它。不是提交路径。 |
原则：**已提交的侧车携带判断**（代理或人类必须做出的决定）。**其他一切都可以通过源代码重新生成**，因此被 gitignored。
**一次性设置：
```bash
asd init
```
```
initialized at ./.asd-state.db
.gitignore: updated (.asd-state.db and .asd/v1/ ignored — both are local derived state)
ASD git hooks installed (.asd/hooks/):
pre-commit trigger: git commit
command: asd conclusions export
purpose: write committed conclusions (decisions/hazards/recipes/…) to .asd/conclusions/*.jsonl
post-merge trigger: git merge / git pull
command: asd conclusions import && asd index .
purpose: import committed .asd/conclusions/ into local ledger and rebuild index
post-checkout trigger: git checkout / git switch
command: asd conclusions import && asd index .
purpose: sync local db to the checked-out branch's sidecar state
core.hooksPath → .asd/hooks (hooks are now active)
To skip hook installation: asd init --no-hooks
To review hooks later: asd hooks
```
`asd init` 后，预提交钩子会自动运行 `asd conclusions export` - 无需手动步骤。
**克隆后 onboarding：
```bash
git clone <repo>
asd init # 安装钩子，更新 .gitignore
asd conclusions import # 加载 .asd/conclusions/*.jsonl → 本地账本
asd index . # 从源代码重建派生语义索引
asd mcp install # 在您的代理工具中注册 asd-mcp
```
## 索引
```bash
asd index . # 索引当前目录
asd index . --verbose # 显示每个文件及其处理过程，列出跳过的文件
```
标准输出：
```
Indexing 42 files under . …
Done. 187 symbols, 187 effects. (12 files skipped — run with -v to list)
```
无法识别的文件类型（`.yaml`、`.json`、`.md` 等）在标准模式下被静默跳过，在 `--verbose` 模式下列出带有 `[skip]`。跳过计数始终包含在 JSON 摘要中。
## 表面
- **`asd`** — CLI：导航（`architecture`、`search`、`trust`、`map`）、变更准备（`prepare-change`、`impact`、`checklist`、`since`、`investigate`、`annotate-commit`、`task-close`、`test-summary`）、账本（`ledger`、`invariant`、`conclusions`、`scratch`、`think`）和管道（`init`、`index`、`sync`、`audit`、`hooks`、`mcp`、`skill`、`watch`）- 参见 [`asd --help`](docs/FEATURES.md) 获取完整的功能集
- **`asd-mcp`** — stdio MCP 服务器，向编码代理公开 63 种工具
- **`asd-serve`** — HTTP 服务器 + Lens 审查 UI
## MCP 工具
代理通过 **63 个 MCP 工具** 访问 ASD，涵盖代码搜索/读取、调用图、导航（`architecture`、`trust`、`endpoints`、`dead_code`）、影响和变更分析、决策账本、不变性、影响、结论、草稿笔记、代理思考、反馈和审计 - 例如 `code_search`、`code_read`、`callers`、`callees`、`context_for`、`impact`、`prepare_change`、`since`、`architecture`、`trust`、`ledger_append`、`invariant_add`、`effect_declare`、`conclusions_export`、`scratch_write`、`think_speculate`、`feedback_promote`、`audit_verify`、`reindex`。完整列表在 [docs/FEATURES.md](docs/FEATURES.md#mcp-tools)。
## 文档
**开始使用：**
- [逐步指南](docs/WALKTHROUGH.md) — 安装 → 每日循环 → 底层发生的事情 → 同时使用 ASD + CTXone
- [功能和命令参考](docs/FEATURES.md) — 每个命令、原始功能和 MCP 工具的解释
- [联邦](docs/FEDERATION.md) — 将 ASD 指向多个存储库以获取跨存储库边缘和决策感知影响（`asd repo edges/impact`）
**参考：**
- [MCP ↔ CLI 映射](docs/mcp-cli-mapping.md) — 两种命名约定并排
- [存储库注册表](docs/repo-registry.md) — 共享的多存储库注册表（`asd repo`）
- [初始读取提示](docs/initial-read-prompt.md) — `asd think` / `asd map` 背后的冷启动定向提示
- [与 RTK 配对](docs/PAIRING_WITH_RTK.md)
**许可：**
- [许可和版本](LICENSING.md) — BSL-1.1 普通英语 + OSS / 团队 / 企业
## 许可和版本
ASD 是 **开源、商业支持的**，并以三个版本提供：
- **OSS** （此存储库）— 完整的开发者引擎：索引、账本、影响、调用图、影响分析、不变性、存储库内跨服务边缘和代理入职。自我托管，无需帐户。
- **团队** — 跨存储库层（投资组合架构、跨存储库影响和死端、团队共享的运行时信心），与 **[CTXone](https://github.com/ctxone/ctxone)** 作为共享团队内存配对。
- **企业** — 组织规模的治理：端点注册表、变更治理门、审计/SIEM 导出、组织仪表板和基于 RBAC 的代理部署。
代码在 **BSL-1.1** 下许可，并转换为 **Apache-2.0**，在每个版本发布四年后 - 内部使用免费；重新分发或托管销售需要商业许可。完整的普通英语摘要和版本分解： **[LICENSING.md](LICENSING.md)**。团队/企业或商业问题： [licensing@agentstatelabs.com](mailto:licensing@agentstatelabs.com)。
