Agentic Task System (ATS)

你一直没用上的最佳 AI Agent 记忆，其实就在任务管理器里。

ats 是一个 MCP 服务和 CLI，可将 AI Agent 上下文保存在你已经在维护的任务系统中——TickTick、Taskmaster、Beads、Obsidian、Notion、GitHub、Airtable、Google，也可以通过复合适配器同时连接多个系统。它会检索相关任务、笔记、决策和运行手册，并保留来源信息；如果当前适配器支持写入，也可以将结果写回。适用于 Claude Code、Claude Desktop、Cursor 和任何 MCP 客户端。

适配器，而非迁移。 你的任务应用、代码库或知识库仍是权威数据源。ATS 会将其映射为统一的任务契约；可选缓存和向量索引可以改善检索，但绝不会成为需要人们另行编辑的第二份记录。它以任务为核心：任务是主干，GitHub issue 和 Notion 规范等辅助材料则作为上下文检索。

两层，一个 CLI：任务和知识图谱。 任务层有意采用记录式设计——每条记录都保存在一个后端的项目和字段中，并以该后端为权威数据源。但记录式层在结构上无法容纳 Agent 会积累的另一类内容：从任意来源撰写、涉及不同主题并汇集到同一空间的持久知识。知识图谱层——ats kg（kg 即知识图谱）——正是 ATS 对此的解决方案：带有来源信息和时间有效性的主语–谓语–宾语事实，由 Agent 从任何地方（一次调用、一个任务、一个代码库或一段聊天）提出，经人工确认，并可在一个位置查询，无论相关工作位于哪个后端。内置存储是嵌入式的，且无需依赖项。若需使用专用图引擎，推荐搭配 Graphiti 作为图数据库服务，以及 LadybugDB 作为嵌入式图数据库：ats kg export --cypher 会生成可由 LadybugDB 加载的脚本（服务端引擎可使用 --dialect neo4j|falkordb，并且可重复运行）；ats kg export --graphiti 会生成包含来源记录的 episode JSONL，供 Graphiti 导入管线使用。

npm install -g @reneza/ats-cli @reneza/ats-adapter-ticktick
ats config use ticktick
ats auth login
ats find "deployment runbook"

一次 ats find 同时搜索 GitHub + Notion + TickTick。ATS 使用 RRF 对可用的检索分支进行排名，并保留结果的来源信息。

## 架构与信任边界

ATS 将权威记录与其周边的检索机制分离：

AI client or operator
        |
        | local stdio, or token-gated HTTP when self-hosted
        v
ATS CLI / MCP server
        |
        +-- Core: task contract, links, lifecycle, ledger, events
        +-- Retrieval: keyword + native + optional dense branches -> RRF
        |
        v
Adapter boundary (auth, mapping, reads, patch-style writes)
        |
        +-- TickTick / Notion / GitHub / Airtable / Google
        +-- Obsidian / Taskmaster / Beads / OKF files
        |
        +-- derived retrieval state
            corpus cache + optional Qdrant/Ollama index

• 后端仍是权威数据源。 ATS 不会要求用户编辑重复的记忆数据库。写入通过当前适配器进行，由适配器负责特定后端的身份验证、字段映射和深层链接。
• 检索状态是派生数据，而非规范数据。 Core 默认保留五分钟的语料缓存。密集检索为可选功能：适配器可以提供嵌入向量，TickTick 参考适配器可以使用 Qdrant 和 Ollama。没有向量时，关键词和适配器原生检索分支仍会运行。
• 凭据留在适配器边界内。 复合适配器将身份验证委托给各个子适配器，不会额外存储跨来源凭据。其子适配器仍在同一个 ATS 进程中运行；这是路由隔离，而非进程隔离。本地 stdio 不会暴露 MCP 端口。托管蓝图添加了 bearer-token 网关、私有 Qdrant/Ollama 服务，以及一个独立的公共演示后端，供可选的运维控制台使用。
• Core 会报告其能够发现的故障。 检索分支和顶层复合语料故障会返回 degraded 和 warnings。适配器回退中的已知遗漏路径列在权衡与限制下。
• 状态变更可追溯。 结果包含来源溯源信息；find --explain 会显示 RRF 贡献；写入采用补丁语义，受支持的写入可以保留变更前的快照以供撤销。

语料缓存可能包含完整任务记录；查询日志包含搜索文本；操作账本可能包含写入前的快照；Qdrant 负载除嵌入向量外，还可能包含任务文本和元数据。ATS 不会对这些副本应用应用层加密或运行时脱敏。请根据底层任务系统的敏感程度，控制主机访问、备份、保留期限和部署范围。具体行为请参阅检索、状态完整性和部署指南。

部署方式

模式	检索	信任与运维边界
本地 stdio	默认使用关键词／原生检索；仅当适配器提供密集检索时才启用	MCP 端点不会暴露到网络。适配器调用仍可能访问其来源系统；凭据和缓存文件保留在运行 ATS 的机器上。
复合适配器	使用一个合并后的子语料；Core 对关键词和合并后的原生搜索分支进行排序，并通过 RRF 合并可用分支。复合适配器目前不提供子适配器向量搜索。	每个子适配器负责自身的身份验证和映射，但都在同一个 ATS 进程中运行。顶层子语料故障会报告为降级状态；请参阅下文的已知回退缺口。
托管蓝图	关键词／原生检索，加上私有 Qdrant/Ollama 服务	bearer-token MCP 网关和独立的可选运维控制台后端对外开放；Qdrant 和 Ollama 保留在私有服务网络中。Qdrant/Ollama 使用磁盘，而 ats-mcp 运行时文件默认是临时的。你需要负责令牌轮换、持久化、备份、可用性和托管成本。

“无需迁移”意味着没有第二个事实来源，并不意味着完全没有派生存储。

对比

方案	权威记录	额外状态	检索
CLAUDE.md / 记忆文件	为 Agent 维护的 Markdown	文件本身	整文件加载或特定于运行框架的查找
独立记忆服务	特定于 Agent 的数据库	需要维护的语料库和摄取流程	特定于产品
纯后端连接器	源任务应用、代码仓库或保险库	除连接器状态外通常没有	直接获取或后端原生搜索
ATS	源任务应用、代码仓库或保险库	缓存、查询／操作／事件状态；可选的派生向量索引	关键词 + 原生 + 可选稠密检索、RRF、来源追溯、类型化上下文

如果操作上下文已存在于任务系统或已连接的工作工具中，而 Agent 需要跨这些系统进行排序且可追溯的检索，那么 ATS 就很合适。如果整洁的 Markdown 已经是完整的事实来源，且整文件加载的规模仍然很小，那么基于文件的工作流可能更简单。

你将获得的功能

• 双向总线。 Agent 会读取适配器提供的任务字段；如果适配器支持写入，它会将结果写回到你能看到的位置。
• 首次获取即相关。 由能力驱动的分支——关键词和适配器原生搜索，以及在可用时进行的稠密检索——会通过 RRF 融合并保留来源信息，以减少反复搜索和优化的循环。每次 find 都会根据各分支的一致性给出置信度判定（--min-sources N 是对应的门槛），--project 会将其绑定到一个项目；过期的语料缓存会立即响应，同时在后台刷新；如果精确匹配为空（notes find、search、get），则会返回最接近的条目，而不是空结果。
• 可经受重试和并发的写入。 update --append / --prepend 会追加到当前正文；--if-match <contentHash> 仅在正文未变更时写入；create --if-absent 和 --idempotency-key 可确保重试的创建操作返回首次创建的结果。共享 HTTP 请求设有截止时间，并遵循取消信号。读取会重试瞬时故障；变更仅在明确收到速率限制拒绝时重试，因此不会因结果不明确的故障而重放写入。
• 持久化的类型化链接。 一个 Agent 添加 decision / depends-on / output / supersedes 链接；之后在全新上下文中运行的 Agent 会通过 ats context 收到该链接。交接记录保存在任务应用中，而非聊天记录里。
• 执行上下文。 ats intent 会记录结果／原因／完成条件；ats lifecycle 会避免过期上下文影响当前工作；ats security 会为协作客户端记录范围限定的允许／拒绝决策；ats ledger 会记录 Agent 执行的操作以及任务是否取得进展；ats promote 会将探索转化为已承诺的目标；ats hierarchy evaluate 会检查本地工作是否仍支持其上级任务。
• 有界事件。 ats events watch --json 会以 NDJSON 格式发出确定性的 task.created/updated/completed/... 事件，并以 0600 权限暂存，支持待处理／确认恢复和稳定的去重 ID。ATS 仅发出观察结果——使用方仍须在采取行动前评估意图、有效性和安全性。
• 面向 Agent 的任务图。 任务会成为包含证明、写回、审查、生命周期和链接边的结构化节点，而非自由格式的记忆文本；参见 docs/task-graph-for-agents.md。
• 事实层。 ats kg 会在任务旁保存持久化的主语–谓语–宾语知识：Agent 提出事实（一条三元组，或使用 --file 提交 JSONL 批次），由人工审核批准（唯一的写入途径）；ats kg ask 会通过确定性的词法评分、置信度判定和完整来源信息作答——无需 LLM 或图数据库服务，且仅追加的文件会随 ats state export 一同迁移。在暂存任何内容前，门禁会先作出判断：重复内容不执行操作；矛盾内容需要 --supersedes 或 --additive；审核者拒绝过的事实需要 --acknowledge-rejected（退出码为 4）；ats kg pending 会向审核者展示每项提议的影响。撤回和取代操作会关闭事实的有效时间段，而不是将其删除；--as-of 会回答存储在当时所认为的内容；ats kg history 会显示事实的变更链；ats kg nodes 会显示存储了解哪些对象的信息；ats context 会附带与任务相关的事实；--semantic 会选择性地将适配器的嵌入器加入稠密检索分支；ats kg export 支持 LadybugDB/Kùzu、Neo4j、FalkorDB 和 Graphiti。
• 会话索引交接。 编码 Agent 的会话浏览器可以保留原始对话记录分析，而 ATS 则保存与任务关联的持久化摘要；参见 docs/agent-session-index.md。 ATS 管理的执行元数据可以编码在任务正文中，类型化链接放在 ## Related 下，查阅的来源放在 ## References 下。受管理的辅助工具旨在保留人工编写的行和链接；update --content 会替换整个正文，因此向正文添加内容的调用方应使用 --append / --prepend，提供读取到的 contentHash 作为 --if-match 的值，并验证结果。npm run prove:intent 会对执行上下文路径进行确定性合成验证。

如需了解可靠的自动化与信息时效工作流，请参阅 CLI 可靠性：限定范围的分页、有界请求、与载荷绑定的重试／恢复键，以及经审核的事实确认。

最简适配器中立工作流

1. 选择并验证适配器： ats config use <adapter>，按其 README 中的说明进行身份验证，然后运行 ats doctor。
2. 检索工作集： ats find "deployment runbook" --json 会对该适配器提供的分支进行排序，并保留溯源信息。
3. 检查权威条目及其上下文： ats context <project> <task> 使用通用适配器契约，无需适配器专属的备注层。
4. 附加持久的执行上下文： ats intent set <project> <task> --outcome "..." --done-when "a,b" 和 ats link add <src-project> <src-task> <dst-project> <dst-task> --type depends-on。
5. 验证组装好的交接内容： 再次运行 ats context <project> <task>，读取关联的决策、依赖关系、证明、生命周期状态以及相关检索结果。
6. 通过适配器或源应用写入，然后读回。 保持权威后端为最新状态，让下一个 Agent 获取持久状态，而非仅存在于聊天中的交接内容。

自行部署

可选的 运营控制台 是一款面向手机的静态 Web 应用，可部署到 Cloudflare Pages。提供的 Render 蓝图会构建 MCP 网关／服务，以及私有 Qdrant 和 Ollama 服务。

部署后，从 ats-mcp 服务的 Environment 选项卡中复制自动生成的 ATS_MCP_TOKEN，将 MCP 客户端指向 https://<your-mcp-url>/mcp 并设置请求头 Authorization: Bearer <ATS_MCP_TOKEN>，然后设置 TICKTICK_ACCESS_TOKEN 以读取真实任务。更倾向于使用自己的机器或 VPS？这些组件也可以作为普通 Docker 容器运行——请参阅部署指南。

可用适配器

后端连接器可以让 Agent 访问 Notion、GitHub 和任务系统，但仅有访问权限，并不能针对“我对 auth 迁移了解些什么？”之类的问题给出统一的排序答案。ATS 增加了一个通用检索层：复合适配器 会组合已安装的子语料库，为其项目 ID 添加命名空间，合并支持的原生搜索结果，并让 Core 根据来源信息对可用分支进行排序。每个子适配器读取各自的凭据，但所有已配置的子适配器都在同一个 ATS 进程中运行。

适配器	权威数据源	检索或写入说明
ticktick	TickTick OpenAPI v1	无需向量即可进行关键词／原生检索；可选的 Qdrant + Ollama 可添加稠密检索。
obsidian	本地 Markdown 知识库	原生文件、补丁式写入可保留未知的 frontmatter。
okf	Open Knowledge Format Markdown 包	本地包。
taskmaster	本地 .taskmaster/tasks/tasks.json	仓库本地任务状态。
beads	通过 bd --json 访问仓库本地 Beads	支持依赖关系的本地任务状态。
airtable	Airtable REST API（表 = 项目）	适配器范围内的 API 访问。
google	Google Sheets / Docs / Slides	只读。
notion	Notion 数据库 + 页面	集成范围内的访问。
github	GitHub issues + discussions	仓库范围内的访问。
composite	已安装的子后端	组合子语料库，为项目 ID 添加命名空间，合并原生搜索命中结果，并路由写入；它不是独立的记录存储，目前也不公开子适配器的嵌入向量。
things / apple-notes / google-tasks	—	规划中，尚未实现。

各适配器的身份验证和映射说明位于对应软件包的 README 中。欢迎提交 PR——请按以下方式搭建脚手架并根据契约进行验证：

ats adapter new linear              # writes a contract-complete skeleton
ats adapter test ./ats-adapter-linear   # pass/fail/skip per contract check

每个仓库中的 Beads

在包含 .beads 的仓库内运行 ATS；该目录名是默认项目 ID。若要明确指定另一个仓库，请为该命令设置其根目录和项目 ID：

cd /path/to/my-repo
ats config use beads
export ATS_AGENT_ID=worker-a BEADS_ACTOR=worker-a
ats tasks ready --json
ats update my-repo ISSUE --claim
ats link add my-repo ISSUE my-repo PREREQUISITE --type depends-on --native --dry-run

ATS_AGENT_ID 和 BEADS_ACTOR 请使用相同的工作者名称；完成已认领的问题时，Beads 会再次检查认领者身份。

在其他目录中，可使用 ATS_ADAPTER=@reneza/ats-adapter-beads ATS_BEADS_ROOT=/path/to/my-repo ATS_BEADS_PROJECT_ID=my-repo ats tasks ready --json。就绪的任务会生成一个具名 RRF 分支；认领操作和原生依赖关系写入会使用现有的审核关卡。有关工作者身份、依赖关系语义和实际 CLI 验证，请参阅 Beads 适配器指南。

权衡与限制

• 数据新鲜度取决于适配器。 Core 的语料缓存默认 TTL 为 5 分钟。后端同步行为、分页方式以及是否包含已完成的工作会因适配器而异；ATS 不承诺普遍支持实时读取。ats cache sync 可按需刷新缓存（适合通过 cron 调度）——适配器实现了 bulkFetchDelta() 时执行增量刷新，否则执行全量重新获取。
• 密集检索需要额外基础设施。 Qdrant 和 Ollama 可以提升语义召回能力，但也会增加索引、持久化、资源和备份方面的工作。向量不可用时，基础 find 仍会返回关键词／原生结果，不过尝试向量分支可能导致响应降级；仅依赖向量的 hybrid 和 similar 操作仍需要这些基础设施。
• 通用契约有意保持精简。 适配器接口定义了 6 种存储方法以及身份验证生命周期钩子，但实际支持的写入操作、更丰富的字段和原生搜索能力各不相同。假定各后端功能一致前，请先查看适配器 README。
• 降级结果仍然只是部分结果。 ATS 会报告失败或超时的 Core 分支、未能获取的语料来源（包括复合回退获取中的单个项目失败和 TickTick 项目获取失败），以及后端无法读取的原生搜索来源。调用方仍须自行判断部分上下文是否可接受；warnings 会指出缺少什么，但不会说明这是否重要。
• 复合搜索并非语义去重。 ats dedup 是一条独立的分析命令。融合时会按后端命名空间隔离标识（<backend>:<taskId>），因此不同后端中相同的原始 ID 仍会作为不同结果保留；语义上重复的任务在建立关联前仍会分别出现。
• 托管版蓝图是参考部署方案，不是托管服务。 一个 bearer token 即可访问完整的 MCP 工具面；该蓝图不提供按用户或按工具划分的权限范围、多租户 RBAC、高可用性或 SLA。
• 默认情况下，托管版 ATS 的运行时状态是临时的。 该蓝图会持久化 Qdrant 和 Ollama，但不会为 ats-mcp 挂载磁盘；重启或重新部署后，其缓存、查询日志、操作账本和撤销前映像、事件暂存队列以及向量同步元数据都会消失。
• 事件是观察结果，不是授权。 ats events watch 可以报告任务变更，但消费者仍须在采取外部操作前评估意图、有效性和安全性。
• 事实层默认采用词法匹配，并由人工把关。 ats kg ask 通过关键词评分、来源信息和置信度判定确定性地得出结果；--semantic 会选择性地增加一个使用当前适配器嵌入器的密集检索分支，因此需要配置嵌入器。未经人工确认，任何内容都不会进入事实存储——Agent 集中提交的提案会按设计等待审核；重复、矛盾或重申已被拒绝事实的内容也不会进入审核队列，且不会不作说明。
• ATS 策略不是沙箱。 CLI 会执行声明的审批元数据——如果写入目标设置了 intent.approvalRequired，或该操作被列入 security.approvalRequiredFor，写入就会进入 ats review，而不会发送到后端（ATS_REVIEW_ALL=1 会拦截所有写入）——但这只保护 ATS 自身的写入路径。对于遵循约定的客户端，ats security check 仍是应用层的决策点；ATS 不会拦截其外部的 shell、文件系统、网络、模型或机密访问。客户端若直接调用适配器，则会绕过 CLI 的拦截机制。

验证与运行证据

50 个问题的合成记忆检索基准测试 将相同的记忆和查询分别用于 ATS 和 Engram v2.2.1 进行比较：

检索路径	Recall@5
ATS 仅关键词	12/50 (24%)
ATS 本地稠密 + 稀疏检索，混合 RRF	47/50 (94%)
Engram SQLite FTS5，默认 all	20/50 (40%)
Engram SQLite FTS5，any	32/50 (64%)

Engram 和 ATS 混合检索都找到了所有精确标题和简短查询的目标结果。 这个由作者编写的小型测试集针对十条不同的决策记忆，测试了未经改写的自然语言问题；它不能证明产品整体优越性。混合检索结果需要本地嵌入，但不需要向量数据库或托管模型密钥。数据集、原始输出、失败项和复现步骤见上方链接。

• CI 在 Node 20 和 22 上运行完整的仓库检查：lint、公开声明检查、PII 检查、单元测试、适配器和意图证明，以及进度基准测试。
• 发布安全检查会扫描仓库内容和 npm 包 tarball，查找机密、个人路径、已配置的个人数据模式，以及本地配置的拒绝名单条目。它保护的是发布面。运行时，组合适配器还可以通过已配置的脱敏模式，按后端强制执行信任级别——如果路由到 "trust": "public" 子项的写入匹配某个模式，就会被阻止，而不会被静默剥除（参见组合适配器 README）。该检查保护的是 ATS 自身的组合写入路径；它不是通用的数据丢失防护。
• 状态完整性测试与约定涵盖补丁式写入、保留未知字段、明确的存储到 Task 映射、结果来源追踪，以及可解释的 RRF 贡献。
• 检索行为记录了 Core 的分支、语料库缓存、时间预算、分支故障时的优雅处理、使用情况日志，以及影响延迟的因素。

这些检查用于验证仓库行为；它们不构成生产可用性或安全认证。

CLI 界面

# Lifecycle
ats init [adapter]                  # select an adapter and run a health check
ats config use <adapter>            # switch the active adapter
ats auth login                      # delegate login to the active adapter
ats doctor                          # inspect adapter and service health

# Retrieval  (any read command takes --json for piping to jq / agents)
ats find <query> [--explain]       # parallel + RRF + provenance + confidence verdict — DEFAULT
ats find <query> --project <id|name>   # bind retrieval to a project (--projects a,b for several)
ats find <query> --min-sources 2   # keep only results two branches agree on
ats find <query> --fresh           # refresh a stale corpus cache before answering
ats open <project> <task>          # open any adapter item by explicit ids
ats context <project> <task>       # task + valid linked/retrieved context
ats link list <project> <task>     # list portable typed links
ats hybrid <query>                 # dense+sparse retrieval when embeddings exist
ats similar <id>                   # related items when embeddings exist

# Notes-layer shortcuts (currently TickTick and Obsidian)
ats get <id-or-title> [--extract raw|json|yaml]
ats url <id-or-title>              # paste-ready note cross-reference
ats links <project> <task>         # resolve deep-links in a note body

# Authoring
ats create "<title>" [--content ..][--project <id>]
ats create <project> "<title>" --if-absent --idempotency-key <k>   # never a duplicate on retry
ats update <project> <task> [--content ..][--title ..]
ats update <project> <task> --append "- 2026-09-05: shipped" --if-match <contentHash>   # add to the body; write only if unchanged

# Agent execution context (portable across adapters)
ats intent set <project> <task> --outcome ".." --done-when "a,b"
ats promote <src-proj> <src-task> <target-proj> --outcome ".." --done-when "a,b"
ats hierarchy set <project> <task> --kind task
ats hierarchy evaluate <project> <task>
ats lifecycle set <project> <task> --status active --valid-until 2026-12-31
ats link add <src-proj> <src-task> <dst-proj> <dst-task> --type decision --dry-run --explain
ats graph <project> <task> --depth 3 --max-nodes 500
ats context <project> <task>
ats snapshot <project> <task> --depth 3 --max-nodes 500  # content-addressed context with completeness
ats history <project> <task>                   # revisions and field-level changes
ats history <project> <task> --restore <revision> --dry-run

# Facts layer (proposed by agents, ratified by you)
ats kg propose "Acme GmbH" "prefers" "invoices as PDF" --domain sales --source "call 2026-08-01"
ats kg propose "Acme GmbH" "prefers" "invoices as XML" --domain sales --supersedes <fact-id>  # replaces, in one ratification
ats kg propose --file facts.jsonl --domain sales   # one JSON object per line, every line through the gate
ats kg propose "Acme GmbH" "signed" "renewal" --source task://<project>/<task> --tier action-record
ats kg pending                                     # what each queued proposal would do to the graph
ats review approve <id> && ats kg ratify --all     # approval comes from someone other than the proposer
ats kg verify                                      # recheck every fact's source; exit 2 when one is gone or changed
ats kg ask "what does Acme prefer" --domain sales --json            # + confidence.verdict
ats kg ask "what does Acme prefer" --domain sales --as-of 2026-06-30 # what the store believed then
ats kg ask "invoices" --center "Acme GmbH" --semantic               # anchored on one entity, embedder-backed
ats kg nodes acme                                  # what the store knows about whom
ats kg history <fact-id>                           # events and supersession chain
ats kg export --cypher > facts.cypher      # load into LadybugDB / Kùzu, full provenance on every fact
ats kg export --dialect falkordb           # openCypher for FalkorDB / Neo4j, re-runnable
ats kg export --graphiti > episodes.jsonl  # Graphiti episodes with the provenance record
ats kg export --cypher --include-retracted # closed facts too, with tInvalid and who closed them
ats ledger record <project> <task> --action release.verified --advanced true
ats ledger list --actor-kind agent --session <id>   # who acted, agent or human, in which session
ats ledger verify                                   # hash-chained ledger; prints head for --expect-head
ats security set <project> <task> --trust trusted --allow-actions read --allow-resources task:self
ats security check <project> <task> --action read --resource task:self --reason "load context"
ats events watch --json            # NDJSON observations; never launches agents

# Ops
ats create --input task.json --dry-run       # strict JSON file, or --input - for stdin
ats batch changes.jsonl --dry-run             # validate a mutation batch
ats batch changes.jsonl --journal run.jsonl   # apply and resume by stable item id
ats state doctor                              # validate local schemas and file permissions
ats state import bundle.json --force --dry-run
ats auth status --non-interactive             # bounded to 15s; override with --timeout-ms
ats tasks completed 30 --projects <id> --require-complete   # every completion in the window, paged
ats review list                 # writes staged by approvalRequired targets
ats review approve ID && ats review apply --all
ats cache sync                  # refresh the corpus cache (find also refreshes a stale one in the background)
ats cache status                # age, stale / servable / revalidating
ats bench run
ats bench score
ats bench progress --json
ats bench analyze-usage --days 7
npm run prove:intent
npm run prove:taskmaster
npm run prove:beads
npm run prove:progress

经过审核的任务写入会将审批绑定到确切的暂存负载，并在应用前检查当前任务版本。每个项目只能由一个进程认领。 如果应用中断，请检查 ats review list --all：applying 或 failed 项目需要先检查后端，再暂存新的提案。未包含负载摘要的旧版审批也必须重新暂存并审批。

对于要求完整读取的自动化场景，请使用 ats find QUERY --require-complete --fresh --json。过时、降级或明确不完整的结果仍会保留其 JSON 输出，并以状态码 2 退出；普通读取则保留原有的宽松退出行为。Doctor 支持相同的严格选项，并限制每次探测的时长：ats doctor --timeout-ms 1000 --require-complete --json。 状态导入会验证已识别的文件内容和提供的任何校验和，即使使用 --dry-run 也会如此，并且会在写入任何文件之前完成验证。

在任意 MCP 客户端中使用（Claude Code、Claude Desktop、Cursor、Windsurf、OpenCode）

@reneza/ats-mcp 将活动适配器公开为一组工具，涵盖检索、CRUD 和执行上下文（find、get_task、create_task、set_task_intent、add_task_link、resolve_task_links、context_for_task、record_action、undo_write、poll_task_events 等）。对于 Claude Code，这能在不同会话之间提供持久上下文，同时不会取代作为事实来源的任务系统；可选缓存和向量索引仍是派生的检索状态。

ATS 通过 stdio 使用 MCP，因此任何能够启动 stdio MCP 服务的客户端都可以使用。只有配置文件和包装键有所不同；二进制文件（ats-mcp）及其 ATS_ADAPTER 环境变量在所有客户端中都相同。

客户端	配置文件位置	包装键
Claude Code	claude mcp add（见下文）	不适用
Claude Desktop	claude_desktop_config.json	mcpServers
Cursor	~/.cursor/mcp.json	mcpServers
Windsurf	~/.codeium/windsurf/mcp_config.json	mcpServers
OpenCode	opencode.json	mcp（结构不同，见下文）

# Claude Code
claude mcp add ats -e ATS_ADAPTER=@reneza/ats-adapter-ticktick -- ats-mcp

// Claude Desktop / Cursor / Windsurf — identical `mcpServers` shape
{
  "mcpServers": {
    "ats": { "command": "ats-mcp", "env": { "ATS_ADAPTER": "@reneza/ats-adapter-ticktick" } }
  }
}

// OpenCode (opencode.json) — local stdio server, note `command` is an array
{
  "mcp": {
    "ats": {
      "type": "local",
      "command": ["ats-mcp"],
      "environment": { "ATS_ADAPTER": "@reneza/ats-adapter-ticktick" },
      "enabled": true
    }
  }
}

请先将二进制文件安装到 PATH 中（npm i -g @reneza/ats-cli），或者在客户端无法继承 shell 的 PATH 时使用 ats-mcp 的绝对路径。

约定

• Wiki 项目。 指定的项目（默认为 Permanent Notes）用于保存持久知识；其他项目用于保存临时任务。
• Agent 数据笔记 = 正文中包含围栏代码块 json / yaml 的笔记，可通过 ats get <title> --extract json 提取。
• 交叉引用 = 适配器原生的深层链接——使用 ats url <title> 生成，不要手动编写。
• 完整规范：docs/wiki-conventions.md。

状态完整性

ATS 会测试托管元数据重写是否保留人工编写的字段，要求显式执行存储到 Task 的映射，并保留结果来源信息（sources、find --explain）。覆盖范围和原始更新行为因适配器而异。发布安全检查（check-no-pii.mjs）会在仓库或软件包内容中出现受检查的个人数据模式时导致构建失败。完整说明：docs/state-integrity.md。

关于 Agent 端的操作模型，请参阅 docs/task-graph-for-agents.md：任务文本是面向人类的呈现形式，但执行层需要结构化链接、证明命令、审查要求和写回目标。

参与 ATS 开发

欢迎贡献——包括修复错误，尤其欢迎在 packages/adapter-* 下添加新适配器。 开发环境设置和适配器模式请参阅 CONTRIBUTING.md；如果你使用编码 Agent 处理此仓库，请参阅 AGENTS.md。在源代码上工作时，pi-codegraph 会为你的 Agent 提供单体仓库的调用图，包括适配器模式和核心变更的影响范围，让它不必在每个会话中重新阅读整个代码树。

发布与许可证

v0.17.0 新增了支持阻塞项识别的 Beads 就绪任务检索、命名原子认领、原生依赖项写入，以及真实的 CLI 并发检查。此版本还修复了命名撤销选择问题，并更新了兼容依赖项。完整历史记录：CHANGELOG.md。

MIT。请参阅 LICENSE。

如果 ATS 对你有帮助，请考虑点一个 ⭐，这有助于其他人发现它。