Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
project-context
Agent-maintained project knowledge layer. Commit-driven, markdown + frontmatter, generic CLI.
本文档同时维护使用方式、架构边界与当前限制。
Status: MVP (v0.1)。MVP 范围见本文档底部"Limitations"。
这是什么
每次开新 agent session 时,agent 都要重新 grep 项目结构来理解代码。project-context 把这层"项目知识"持久化下来 —— 跟着 git commit 增量演进,agent 自己维护,新 session 启动时按需注入。
核心概念:
- modules:跟 package / 目录对齐的骨架知识(一份 .md / 一个包)
- concerns:跨包的横向关注(IPC、agent lifecycle 等,由 agent 在 update 时提议;MVP 阶段不自动建)
- manifest.yaml:索引文件,反查"哪些知识覆盖某文件"用
- stale 标记:知识过期时打标,等下次任务用到时按需 refresh(JIT,Phase 2)
- auto_update flag:frontmatter 里设
auto_update: false可冻结某个 module 不被自动维护
安装 / 运行方式
在本仓库内(开发态)
project-context 是 monorepo 内的 workspace 包,不需要独立安装。直接:
# 1. 安装依赖(仓库根)
pnpm install
# 2. 编译
pnpm --filter project-context build
# 3. 跑 CLI(仓库根,绝对路径)
node packages/project-context/dist/cli.js <command>
通过 pnpm exec(任意 workspace 子目录都能跑)
pnpm --filter project-context exec project-context <command>
通过 npx(包发布或全局装之后)
未来发布到 npm 后:
# 全局装
pnpm install -g project-context
project-context <command>
# 或者按需 npx
npx project-context <command>
项目内 devDep(推荐生产部署方式)
pnpm add -D project-context
# package.json 里就有 bin shim 了:
node_modules/.bin/project-context <command>
# 或 pnpm 脚本里:
# "scripts": { "kctx": "project-context update" }
开发模式(不需要每次 build)
pnpm --filter project-context dev # tsx watch src/cli.ts
依赖项:Node ≥ 18,且仓库必须是 git。MVP 强制要求;非 git 项目报错退出。
Quick Start(3 步跑通)
# 1) 初始化:扫描 monorepo / pnpm workspace,给每个有源码的 package 建一份空壳 .md
node packages/project-context/dist/cli.js init
# 2) 看产出
ls .cindy/project-knowledge/modules/
cat .cindy/project-knowledge/manifest.yaml
# 3) 模拟有 diff 时的 dry-run(不调 LLM、只算映射)
node packages/project-context/dist/cli.js update --since HEAD~5 --check-only
# 4) 反查"改了某个文件影响哪些知识"
node packages/project-context/dist/cli.js query --files packages/maker-core/src/agents/base-agent.ts
Commands
init [--bootstrap] [--prune]
扫描仓库、按 package manager 约定建 modules/ 骨架。幂等:已存在的 .md 不覆盖。
发现优先级:
.cindy/project-knowledge/config.yaml的module_roots(显式)pnpm-workspace.yaml的packages字段package.json的workspaces字段- 都找不到 → 报错让你写 config.yaml
每个候选目录会过一道源码启发式:目录里没有任何 .ts/.js/.go/.rs/.py/.html/.css/... 等源码后缀就跳过(用来排除 *-bin 这种纯二进制镜像包)。
选项:
| Flag | 作用 |
|---|---|
--bootstrap |
跑一次"全工程扫一遍 + LLM 提议跨切关注"。MVP 占位,暂未真跑,会输出黄色提示 |
--prune |
把 orphan 模块(discovery 不再发现的 .md)从 disk 删掉。默认只报告不删 |
典型输出:
project-context init
repo root: D:/work/cindy
discovered modules: 8
created: 8, skipped: 0
+ apps--desktop
+ apps--landing-page
+ ...
wrote default .cindy/project-knowledge/config.yaml
manifest: .cindy/project-knowledge/manifest.yaml
update [--since <ref>] [--check-only]
按 git diff 增量更新受影响的知识文件。
流程:
- 拿一个文件锁(
.cindy/project-knowledge/.lock),抢不到就跳过本次(防并发) - 算
last_synced_commit..HEAD的 diff - 过
.gitignore+ 内置 ignore + config.ignore 三层过滤 - 反查每个改动文件覆盖的知识 ID
- 对每个受影响的 ID:
- 小 diff(≤ 5 文件 且 ≤ 200 行,可在 config.yaml 调)→ 调 agent 适配器重写正文
- 大 diff → 标
stale: true,等下次任务 refresh auto_update: false→ 完全跳过(不重写也不标 stale)
- 收集"未被任何知识覆盖"的改动文件,提示考虑加新 module / concern
选项:
| Flag | 作用 |
|---|---|
--since <ref> |
覆盖 diff 起点。默认用 manifest 里 last_synced_commit。常用 --since HEAD~5 测试 |
--check-only |
只打算盘不写盘:列出会更新 / 标 stale / read-only 跳过的 ID,不调 LLM 不改文件 |
典型输出:
project-context update
diff: 4cc6490..6838258
updated: 1, staled: 1, read-only skipped: 0, uncovered files: 1
~ packages--maker-core (rewrote)
s apps--desktop (staled)
uncovered files (consider adding a module/concern):
- .gitlab-ci.env
真正调 LLM 需要本机有
claudeCLI 在 PATH 里且已登录(详见 Adapter 节)。
refresh [ids...] [--all | --stale] [--check-only] [--force]
从当前源码重建知识正文,不依赖 git diff。冷启动 / 历史代码补完 / 修复 stale 都用这个。
适合场景:
- 首次冷启动:
init只建空骨架(TODO 占位),refresh --all让 LLM 一次性把所有 module 填满 - stale 修复:之前 update 因 diff 太大标了 stale,跑
refresh --stale集中重生 - 某模块单独刷:只想看一个 module 的产出,
refresh packages--maker-core
scope 三选一(互斥):
| 用法 | 作用 |
|---|---|
refresh <id> [<id> ...] |
刷指定 ID(可多个) |
refresh --stale |
只刷标了 stale 的 |
refresh --all |
全刷一遍 |
选项:
| Flag | 作用 |
|---|---|
--check-only |
干跑:列出 target 不调 LLM 不写盘 |
--force |
默认跳过 auto_update: false 的 module;加 --force 强制刷 |
机制:refresh 通过 adapter 调 claude -p,但不喂 diff。只告诉 agent:"你要刷的 module 覆盖 <covers> 路径,请用你的 Read/Glob/Grep 工具自己探索源码,然后写新正文"。claude 在 headless -p 模式下默认带工具访问,所以可以自主爬。
典型输出:
project-context refresh
targets: 8 (scope=all)
[1/8] apps--desktop refreshing...
done (32.4s)
[2/8] apps--landing-page refreshing...
done (8.1s)
...
refreshed: 7, skipped: 0, failed: 1
x packages--@cindy/mcps claude-code adapter: timed out after 600000ms
成本提醒:
- 单个 module refresh 估算 10-30k token + ~30-90s 时间(取决于包大小)
refresh --all在 8 module 的项目上估算 100-200k token + 5-15 分钟- 强烈建议先跑一个 module 试水(
refresh packages--maker-core --check-only→ 然后真跑一次 → review 输出)再决定是否--all
query --files <list> [--format ids|paths|json]
反查:给一组文件路径,输出覆盖它们的知识 ID。
# 单文件,默认 ids 格式
node packages/project-context/dist/cli.js query \
--files packages/maker-core/src/agents/base-agent.ts
# 多文件 + JSON 格式
node packages/project-context/dist/cli.js query \
--files packages/maker-core/src/agents/base-agent.ts,apps/desktop/src/main/index.ts \
--format json
# 输出:
# {
# "ids": ["apps--desktop", "packages--maker-core"],
# "paths": [".../modules/apps--desktop.md", ".../modules/packages--maker-core.md"],
# "stale": []
# }
输出格式:
--format |
输出 |
|---|---|
ids(默认) |
每行一个 ID |
paths |
每行一个 .md 绝对路径 |
json |
含 ids / paths / stale 三个数组 |
主要给 agent harness 用:把改动文件丢进去 → 拿 .md 路径 → 拼到 system prompt。
产出物(.cindy/project-knowledge/ 长什么样)
<repo-root>/.cindy/project-knowledge/
├── config.yaml # 用户可编辑配置(init 时写默认)
├── manifest.yaml # 索引(机器维护,可从 .md 重建)
├── .lock # update 运行时的临时锁文件(自动清理)
├── modules/
│ ├── apps--desktop.md
│ ├── packages--maker-core.md
│ └── ...
└── concerns/ # 空目录,等 Phase 2 自动填
单份 module .md 长这样:
---
id: packages--maker-core
type: module
covers:
- packages/maker-core/**
depends_on: []
last_synced_commit: 4cc6490af1399d087977a3e62994264d6fe94fc1
last_synced_at: '2026-05-11T09:44:49.539Z'
stale: false
stale_reason: null
auto_update: true
schema_version: 1
---
# packages--maker-core
## 是什么
...
## 关键抽象 / 核心代码地标
...
## 模块边界
...
## 不要做的事
...
## 演进备忘
(仅追加,记录重大改动)
Frontmatter 字段:
| 字段 | 类型 | 说明 |
|---|---|---|
id |
string | 全局唯一,一般是 path 转 kebab |
type |
module | concern |
决定放哪个子目录 |
covers |
glob[] | 反查代码 → 知识的关键 |
depends_on |
id[] | 注入时一跳扩展("用 A 必带 B",Phase 2) |
last_synced_commit |
sha | diff 起点 |
last_synced_at |
ISO time | 调试 |
stale |
bool | 标记是否过期 |
stale_reason |
string | null | 调试,记录是哪个 commit 触发的 stale |
auto_update |
bool(默认 true) | 设 false 则 update 完全跳过此知识 |
schema_version |
int | 格式升级用 |
配置(.cindy/project-knowledge/config.yaml)
init 第一次跑时会写一份默认配置,后续手动编辑:
# 自动发现 modules 的根路径(不写则按 package manager 约定)
module_roots:
- packages/*
- apps/*
# 额外 ignore(叠加在 .gitignore + 内置默认之上)
# 内置默认包括:node_modules, dist, build, *.lock, *.min.js, *.snap 等
ignore:
- apps/some-vendored-thing
# 小 diff 阈值
small_diff_threshold:
files: 5
lines: 200
# Adapter
agent: claude-code # MVP 仅支持 claude-code,未来 codex / custom
agent_options:
timeout: 120 # 秒,超时杀进程
# model: opus # 可选,传给 claude --model
# command: /path/to/claude # 可选,覆盖默认 PATH 搜索
Adapter(LLM 怎么被调)
MVP 内置一个 adapter:claude-code。
机制:在子进程里 spawn('claude', ['-p', '--output-format', 'text']),prompt 通过 stdin 喂入,结果从 stdout 读出。
前置条件:
- 本机 PATH 里有
claude可执行(Claude Code CLI) - 已登录(
claude自带的 OAuth 凭证)—— 不需要 ANTHROPIC_API_KEY
失败模式:
claude不在 PATH → 报错"claudeCLI not found in PATH"- 退出码非 0 → 报错并捕获 stderr
- 超时 → 杀子进程报错
- 任何失败 → 该 module 标 stale,update 继续处理后面的 ID
后续可按 src/adapters/types.ts 的接口增加 codex / custom adapter。
常见接入工作流
Cindy Desktop(本仓库默认 harness,开箱即用)
Cindy Desktop 已内置自动入口:每次创建新的 Claude Code、Codex 或 Pi session 时,main 进程会探测 cwd 下是否有 .cindy/project-knowledge/TOC.md。存在且非空时,只把这个文件的短路径提示包成 <project-context-toc> wrapper;agent 在任务相关时再读取 TOC 和对应知识文件。TOC 正文不再占用每个 session 的启动上下文,缺失则 silently skip。
- 无需任何 UI 开关:所有用户默认启用(不再走"实验功能"入口)
- 目录探测:以 cwd 为根,命中
.cindy/project-knowledge/TOC.md才触发 - per-session 快照:是否注入会回写到
sessions.used_project_context列;老 session 维持启动时刻状态,不被后续追溯 - 可视提示:chat footer 的 Brain icon + tooltip "项目知识库已加载"(4 语言已对齐)
注入逻辑实现:apps/desktop/src/main/maker-ipc/projectContextInject.ts。100KB 硬上限超出截断尾部并加 truncated="true" 标记。
自动 update:本地 git post-commit hook(推荐主路径)
仓库根的 .git/hooks/post-commit(手动建文件,加可执行权限):
#!/bin/sh
# 异步、后台跑,不阻塞 commit
(node /absolute/path/to/packages/project-context/dist/cli.js update > /tmp/pctx.log 2>&1) &
或团队场景用 husky / lefthook 之类工具管理。
让 agent 启动时拿到知识:harness 集成
任何 agent harness(Claude Code、Codex CLI、Cindy、Cursor)启动新 session 前调一次:
# 收集相关文件
files=$(git diff --name-only main...HEAD | tr '\n' ',')
# 查相关 .md 路径
paths=$(node packages/project-context/dist/cli.js query --files "$files" --format paths)
# 拼到 system prompt(具体怎么拼看 harness)
for p in $paths; do
cat "$p"
done > /tmp/system-prompt-append.md
把 update 接到 Claude Code 的 Stop hook
Claude Code 的 hooks 配置里加:
{
"Stop": "node /absolute/path/to/packages/project-context/dist/cli.js update"
}
每次 agent 完成一轮就跑 update —— 适合 agent 频繁改代码不立即 commit 的场景。
怎么手动控制某个 module
冻结某个 module(不让 update 改):
编辑 .cindy/project-knowledge/modules/<id>.md 的 frontmatter,加:
auto_update: false
下次 update 见到这个就直接跳过(输出 r <id> (auto_update=false))。
清理 orphan:
# 默认只报告
node packages/project-context/dist/cli.js init
# 实际删除
node packages/project-context/dist/cli.js init --prune
强制重生某 module:
# 单个
node packages/project-context/dist/cli.js refresh packages--maker-core
# 所有 stale 的
node packages/project-context/dist/cli.js refresh --stale
# 全量冷启动
node packages/project-context/dist/cli.js refresh --all
详见上面的 refresh 命令小节。
Limitations(MVP 没做的)
init --bootstrap接收 flag 但暂未真扫 concerns(注:填模块正文用refresh --all,bootstrap 只是用来发现新 concerns,Phase 2)inject命令未单独封装(用 query 拼即可)- 仅
claude-codeadapter;codex / custom 待做 depends_on字段写入但 query 不做扩展(一跳)- 没有 token budget 排序
- 没有"跨进程更稳的锁"——
.cindy/project-knowledge/.lock是简单文件锁,崩溃时可能残留(手动删) - 演进备忘没有膨胀防护(Phase 3)
Troubleshooting
| 症状 | 原因 / 解 |
|---|---|
Not inside a git repository |
当前目录不是 git 仓库。git init 或换路径 |
Discovery returned 0 modules |
没有 pnpm-workspace.yaml / package.json workspaces,或都没匹配。在 config.yaml 写 module_roots |
Detected go.mod / Cargo.toml |
MVP 不支持 Go/Rust 自动发现。手写 module_roots 即可 |
update 输出 another instance is running |
上次跑挂了残留 .lock。删 .cindy/project-knowledge/.lock 重试 |
update 报 claude CLI not found |
装 Claude Code CLI 或在 config.yaml 写 agent_options.command 指自定义路径 |
| init 报某个目录是 orphan 但不该是 | 该目录里全是非源码后缀。要么手动建一份 .md(init 不会覆盖),要么扩展 SOURCE_EXTENSIONS(src/discovery.ts) |
配置字段与当前限制以本 README 和 src/ 实现为准。