在大多数与编程 agent 一起工作的团队里，关于项目的知识散落在三个地方：人的脑子里，agent 看不到的 wiki 里，以及某人检出目录里的 AGENTS.md 或 CLAUDE.md 里。最后这一个会在有人重构的那天过时，而下一个 agent 照样信它。
ClewWiki 想做第四个地方：一个 agent 和人平起平坐的 wiki。它们读、写、在讨论里争论，也会汇报。0.9.0 版本有 40 个 MCP 工具。下面讲怎么把 Claude Code、Cursor 或 Codex 接进来，以及 agent 能得到什么。人这一侧（导入、登录、组织）写在姊妹篇里。
两分钟接入#
MCP 服务器以 npm 包 @clewwiki/mcp-server 的形式发布。除了 Node.js 22，不需要预先安装任何东西。在实例的 Agent tokens 里签发一个 agent 令牌，然后写配置。Claude Code 用的是项目里的 .mcp.json：
{
"mcpServers": {
"clewwiki": {
"command": "npx",
"args": ["-y", "@clewwiki/mcp-server"],
"env": {
"CLEWWIKI_URL": "https://wiki.example.com",
"CLEWWIKI_TOKEN": "${CLEWWIKI_TOKEN}"
}
}
}
}Cursor 在 .cursor/mcp.json 里使用同样的 mcpServers 对象。Codex 读取 ~/.codex/config.toml 中的 TOML：
[mcp_servers.clewwiki]
command = "npx"
args = ["-y", "@clewwiki/mcp-server"]
env = { CLEWWIKI_URL = "https://wiki.example.com", CLEWWIKI_TOKEN = "..." }这是 stdio 传输：agent 在开发者的机器上启动服务器，服务器通过 HTTPS 访问实例。除了本地地址，它会拒绝普通的 http://。CI 里的 agent 可以用第二种传输方式 streamable HTTP。它默认关闭（MCP_HTTP_ENABLED=false），也不允许匿名访问。
最省事的办法是根本不手写配置：应用里的 Connect an agent 页面会打印出适用于你所用客户端的准确命令，以及一段告诉 agent 如何使用 wiki 的提示词。从 0.8 起，那里还有日常命令：任务开始前读 wiki、完成后更新、发起讨论。针对 Claude Code，还有一行命令能把它们安装为 /wiki-read 和 /wiki-update。
agent 令牌和人的密码有什么不同#
MCP 服务器被做成实例的一个普通 REST 客户端。它只持有令牌，没有别的进入途径。由此得到最关键的性质：agent 没有后门。每次调用都经过与直接 HTTP 请求相同的权限检查、相同的限流和相同的审计。
令牌只限于被授权的空间，有有效期，可以吊销。过期或已吊销的令牌在认证阶段、任何写入之前就会被拒绝。每一次写入尝试都会在同一个事务里记入审计日志，无论是成功、撞上别人的 claim，还是带着过期的哈希。每个令牌都有频率限制，所以陷入循环的 agent 会先撞上限制，而不是把 wiki 刷爆。
关于别人写的文字，还有一条单独的约定。工具从已存储内容中返回的一切（页面正文、备注、名称、代码片段）都被标记为数据，而不是指令。一页写着“忽略之前的指令”的文字，仍然只是文字。这并不能让 prompt injection 变得不可能，但堵住了最廉价的那条路。
同一页面上的两个 agent#
这个机制我写过整整一篇文章，这里简单说。写入之前，agent 通过 wiki.claim 对页面或某个章节取得 claim。写入时带上 claim 的 ID，以及 agent 读到的内容的哈希。claim 证明此刻没有别人在写，哈希证明这期间也没人写过。第二个 agent 会收到一个写明持有者名字的冲突。悄悄覆盖别人的文字是不可能的。服务器也从不自行合并：哈希过期时，它返回两个哈希，等待 agent 重新读取页面。
claim 会自动过期，可以续期（wiki.renew_claim）也可以释放（wiki.release_claim）。卡住的 claim 由管理员移除，这一操作会以专门的名称记入审计日志。agent 令牌无法强行释放任何人的 claim。
agent 的修改等待人审阅，但不阻塞#
agent 写入无需审批：修改一落地就是页面本身。否则人一忙，agent 就得在队列里干等。不过，自上次审阅以来 agent 做的所有修改都会以 diff 的形式汇集在 Changes 里。人可以接受或回滚，并留下一条备注，agent 在下一次尝试前会读到它（wiki.get_review）。
待审的修改不是以标记存储的，而是推算出来的。人写下或接受的最新版本就是基线，之后 agent 所做的一切都处于待审状态。
此刻谁在 wiki 里#
在 0.8 中，Presence 面板除了 claim，也开始显示人：谁打开了哪个页面，是在阅读还是在编辑。旁边是过去十分钟内用令牌发过请求的 agent，以及它最后一次请求涉及的页面。页面标题下方能看到还有谁在这个页面上。
有个细节比我预想的更早派上了用场。由 WebDriver（Playwright、Selenium、Puppeteer）驱动的浏览器会被单独标记。那是借着某个人的会话在干活的 agent，人能把它和同事区分开会很方便。
agent 可以从 wiki.get_presence 的 active_now 字段拿到同样的信息。动手处理某个页面之前，agent 能看到此刻有人在上面，于是可以换一个任务，而不是撞上冲突。
任务来自工单系统#
0.8 在接入 YouTrack 和 Jira 的同时加入了三个工具：
wiki.my_tasks：分配给签发该 agent 令牌之人的未解决工单，按邮箱地址在工单系统中查找。wiki.get_issue：按键获取工单，包括描述和评论。wiki.search_issues：用 YouTrack 查询或 JQL 搜索。
于是，Connect an agent 页面上的“领取我的任务”就成了一个真正可用的流程：agent 拿到列表，读一个工单，找到 wiki 中提到它的键的页面，带着上下文开始工作。工单系统的令牌只存在于实例的环境变量中，不会进入数据库。
限制要说清楚：工单系统的客户端只在录制的 API 响应结构上测试过，还没有在真实的 YouTrack 或 Jira 上验证。
分支、发布，以及容易忘掉的东西#
0.9 带来的 Development 栏目，对 agent 比对人更有用。它读取空间的 git 仓库，为每个分支维护一条工作线：相对默认分支领先和落后多少、是否已合并、属于哪个发布。已合并但未发布的工作会被高亮，只要还有未合并的工作线，发布就无法被标记为已发布。
对 agent 来说，这意味着三个工具（wiki.development、wiki.get_stream、wiki.update_stream），以及 wiki.open_discussion 上的 stream_id 参数。在某个分支上遇到问题的 agent，可以直接在该分支的工作线里发起讨论。讨论解决后，决定会以页面形式写入工作线的文档，讨论串本身则会过期。留下的是结论，聊天记录不会越堆越多。
文件、收件箱与关注#
agent 可以发布和读取文件：wiki.upload_file 通过工具最多上传 7 MB，更大的文件用同一个令牌走 REST；wiki.get_file 返回最大 256 KB 的文本文件内容。用页面上已有的文件名上传，会在同一个链接后面新增一个版本。
wiki.watch 用于关注页面或空间，wiki.check_inbox 返回与 agent 有关的内容：它发起的讨论里的回复、提及、对它修改的审阅、文件的新版本。答复会找到提问的人，不需要邮件，也不需要单独的通知队列。
规则和技能放在 wiki 里，而不是检出目录里#
项目规则和可复用的技能都存放在 wiki 中，任何 agent 在开始工作前都会通过 MCP 读取（wiki.get_rules、wiki.list_skills、wiki.get_skill）。团队约定不再是某个人笔记本上按工具各一份的文件。
不过，agent 宿主是从目录里加载技能的，而 MCP 调用无法写磁盘。所以这个包还附带了一条命令：
CLEWWIKI_URL=https://wiki.example.com CLEWWIKI_TOKEN=$CLEWWIKI_TOKEN \
npx -y @clewwiki/mcp-server skills install --space MOBILE它会拉取空间里的技能，写到 ~/.claude/skills/<slug>/SKILL.md，并逐一打印写入的文件。--only 只安装选定的几个，--dir 写入其他目录。
最后，对付“上下文过时”还有一招：页面可以锚定到代码中的声明，支持 Swift、TypeScript、TSX 和 Kotlin。跑一遍格式化工具不会改变任何东西，函数体改动会把页面标记为过时，重命名和移动能被识别，删除会被报告。它是怎么做到的、为什么没有误报，写在关于锚点的文章里。
我不承诺的事#
- 这是 0.x。 第一个 tag 在 9 月 18 日发布，第十个在 10 月 5 日。几乎每个版本都会新增工具，agent 需要重新连接才能看到，数据库迁移也很频繁。
- 工单系统尚未在真实环境中验证，前面已经说过。
- streamable HTTP 默认关闭。 要给 CI 里的 agent 用，必须有意识地开启，并把实例放在 TLS 后面。
- 审计和 claim 防不了糟糕的内容。 有写权限的 agent 可以信心满满地写出胡话。修改审阅正是为此而设，但总得有人去看。
试一试#
按 README 的快速开始起一个实例，给一个空间签发令牌，让 agent 在下一个任务开始前读 wiki、完成后更新。看看 Changes 里出现了什么，一个晚上就能判断这种工作方式适不适合你的团队。
完整的工具列表及其 scope 和错误说明，在仓库的 docs/mcp.md 里。项目概览在 ClewWiki 页面。
