ACStack

ACStack是一个代理编码栈。它帮助编码代理澄清需求，测试有意义的行为，并保持文档与代码匹配。

• ACStack旨在解决编码代理引入的两种常见故障模式
  • 代理在需求明确之前开始构建
  • 代理编写代码，然后创建针对该代码的测试
• ACStack对Claude Code和pi具有一流的支持
  • Claude Code将其作为插件安装
  • PI将其作为NPM包安装
• ACStack介绍了代理如何工作的结构
  • 验证将更改置于共享策略下 orchestrator/AGENTS.md
  • 每次提交都会从diff更新你的规格
• 直接的工作可以由一个代理完成，包括调查、测试、实现和验证
  • 一个验证所有者收集最终的完成证据，重用有效的结果，而不是在每次移交时重复检查
  • 审查深度跟踪受影响的风险；除非用户批准，否则建议进行相邻清理

flowchart TD
    Q{"What kind of<br/>request is this?"} -->|"clear enough to build"| IM["Build it<br/>(/acstack:implement)"]
    Q -->|"something stopped working"| QF["Find the root cause first<br/>(/acstack:quick-fix)"]
    Q -->|"still has open questions"| MP["Answer them first<br/>(/acstack:map)"]
    MP -->|"once the questions are answered"| IM
    IM --> C["Commit, and update the docs<br/>(/acstack:commit)"]
    QF --> C

上面的每个方框都是第2部分。该文件的其余部分是参考。

1. 快速入门

ACStack有一流的支持 克劳德代码 和 π.

1.1. 安装在Claude Code上

你需要Claude Code CLI和Node.js 20或更高版本。

安装插件：

/plugin marketplace add ac8318740/ac-agentic-coding
/plugin install acstack@ac-agentic-coding

然后，在你的项目中：

/acstack:setup

• /acstack:setup 检测项目类型，然后写入 project.yaml 与工作流设置一起放入项目文件夹
• 所有acstack拥有的项目记录都位于每个存储库的一个项目文件夹中，由其所有工作树共享
  • ~/.claude/acstack/bin/acstack project-data path 打印;默认情况下是 ~/.acstack/projects/<key>/，在存储库之外
  • 运行 acstack project-data mode tracked 把记录保存在仓库的 .acstack/ 然后把它们交上去
  • 看到 项目数据在哪里 用于路径、模式和命令
• 迁移旧项目前更新已安装的ACStack工具
  • 停止旧的代理和评论，跑吧 ~/.claude/acstack/bin/acstack project-data migrate，然后使用更新后的工具重新启动
  • 迁移在没有覆盖或Git索引更改的冲突时中止；跟踪的旧路径成为待处理的删除
• 每当SessionStart钩子检测到一个ACStack项目时，它就会加载编排器指令
• 你的克劳德。Md对于特定于项目的内容保持干净
• 从0.8.0之前的版本升级意味着删除一个过时的版本 @import 线(见 文档/ migrate-0.8.md）

1.2. 安装在pi上

相同的项目安装为 π 包和 @tintinweb/pi-subagents 或者 pi-subagents 代表团。

pi install npm:@tintinweb/pi-subagents
pi install npm:acstack

然后，在您的项目中运行 /acstack:setup.

• 每个技能都以与Claude Code相同的名称运行，例如： /acstack:map

  • /acstack map 是一样的
  • 两者都总是运行ACStack技能，即使另一个pi包有一个技能被调用 map

• ACStack的技能故意不表现为 /skill:<name> 命令

  • 这个包不给pi任何技能，所以 /skill:map 从未运行过ACStack的地图
  • 扩展在系统提示符中列出技能，因此当任务匹配时，模型仍然读取一个

• pi/extension.ts 克劳德代码的钩子是做什么的

  • 链接到CLI ~/.claude/acstack/bin/acstack
  • 它将编排器指令添加到ACStack项目中的系统提示符中
  • 它在每个会话的系统提示中列出了ACStack的技能
  • 它在压缩后重新注入切换
  • 随着上下文的填充，它会随着连续性与新鲜度检查点的变化而变化
    • 连续性在同一会话中保持有用的工作上下文，在可用时使用十亿上下文或主机ACP压缩
    • 新鲜的使用 /acstack:handoff 当一个新的窗口或独立阅读帮助更多
    • 在没有设置阈值的情况下，第一次推送是20万个令牌或窗口的一半，以较低者为准
    • 紧急推动是50万代币或80%的窗口，以较低者为准

• ACStack自动包含问题-状态桥接

  • 与 @juicesharp/rpiv-ask-user-question 和Herdr的Pi集成安装，Herdr显示阻塞，而Pi等待答案
  • 已安装的桥可以保持安装状态，而不需要等待两次

• 两个子代理包都通过 pi.subagents 场 package.json

  • @tintinweb/pi-subagents 公开 Agent； pi-subagents 公开 subagent
  • 代理使用子代理包的默认模型
  • 当pi没有列出任何工具时，ACStack在会话开始时发出警告

• 允许委托 ~/.pi/agent/AGENTS.md：

  When an ACStack skill or the ACStack orchestrator says to launch a subagent, you may delegate to it.
  

  • 为 pi-subagents,设置 "toolActivation": "eager" 在 ~/.pi/agent/extensions/subagent/config.json 提供 subagent 从第一回合开始（之后重新启动PI）

• 默认情况下，pi从扩展中获得ACStack的写作风格

  • 运行 /acstack-writing-style default 再次使用捆绑样式
  • 运行 /acstack-writing-style off 禁用样式注入
  • 运行 /acstack-writing-style custom <path> 使用用户拥有的样式文件

2. 三个命令，以及使用哪一个

根据阻碍你的东西来选择：什么都没有，一个bug，或者一个未回答的问题。

首先是两个单词，因为下面的第三个命令使用它们。

• 一幅地图 ACStack是否为一项工作保留了待办事项图
• 一个节点 图表上是否有一个条目：一个要回答的问题，或者一项要做的工作

三个命令：

• 这个要求很明确，可以构建 ——运行 /acstack:implement
  • 它根据您的请求运行第6部分的四个代理
  • 一行更改仍然是一行更改
• 已经建成的东西停止工作了 ——运行 /acstack:quick-fix
  • 它使代理在编辑任何内容之前找到根本原因
• 该请求仍有悬而未决的问题 ——运行 /acstack:map
  • 经纪人一次面试你一轮
  • 每一轮都会问下一轮能回答的所有问题
  • 每个问题都有代理推荐的答案
  • 你对代理推荐的答案提供反馈，而不是从头开始提示
  • 有些请求只需要一个问题
  • 代理人把这个决定作为简短的笔记写在 <project folder>/decisions/
  • 一个大功能可能需要几十个问题
  • 代理将这些问题存储为 地图
  • 你在几个回合中完成地图

2.1. 地图承载着什么

/acstack:map 只有当一次谈话不能解决所有问题时，才能建立一个地图。

每个节点携带五种状态中的一种。

每个节点还记录六件事。

• 之前哪个答案引出了这个问题
  • 你可以按照你做出决定的顺序把决定读回来
• 在这个节点开始之前，还有哪些节点必须完成
  • ACStack使用它来告诉你什么准备开始
• 谁接电话？你，或者单独工作的代理人
• 是什么样的？目的地、常记、决定、研究或工作
• 一个简短的名字，用于标记图中的节点
• 它住在哪里：默认情况下GitHub问题，或markdown文件 <project folder>/maps/ 没有GitHub遥控器

几乎每个节点都用图表来解释自己。

• 入口节点绘制整个地图，并折叠已完成的部分
• 每个其他节点都有自己的问题或变化
• 每个图下面都有一个图例，仅显示该图使用的符号
• 在GitHub上，单击图中的节点以打开其问题

ACStack对完成的地图做两件事。

• 它通过准备启动的节点工作也就是那些没有未完成的东西挡住的开放通道
  • 设置 前沿
• 它把整个地图压缩成一份简报
  • 一个新的代理会话从最后一个代理会话停止的地方开始

ACStack中的每条规则都存在，因为在没有它的情况下，经过几个月的编码代理的实际产品开发，出现了一些问题。

要了解每个步骤的全貌以及它们之间的联系，请阅读 文档/ workflows.md.

3. 配置一个项目和一台机器

项目说明要运行什么。机器说明它能做什么。

• project.yaml 在项目文件夹中保存每个项目范围的设置
  • 文档/ config-reference.md 给出每个键，它的值，它的默认值和什么变化
• ~/.acstack/config.json 保持9 host.* 轴
  • /acstack:host 每台机器一次写入其中的8个，并且 /acstack:setup 写第九个
  • 文档/ dev-setups.md 给出每个轴，读取它的内容，以及如何描述一台新机器
• /acstack:setup 从三个语言配置文件之一复制命令和目录
  • python - pytest, ruff, my my
  • node-typescript - NPM测试，eslint， TSC
  • fullstack-python - Python后端，加上Node或TypeScript前端
• acstack config check 审核项目和机器
  • 当所需的主机轴没有值时，它退出2

4. CLI

四个存储操作携带整个映射。一个固定的路径使得从任何代理会话都可以访问CLI。

ACStack提供了一个Node.js命令行： acstack config， acstack list， acstack node ..., acstack archive.

• map背后的存储提供了四个操作，仅此而已：创建、读取、更新、列表
  • GitHub问题是默认的
    • 每个问题主体的第一行包含该节点的所有边
    • 因此，一个调用读取整个地图
    • 子问题和问题依赖关系反映了这些边缘，所以GitHub自己的界面绘制了地图
  • Markdown文件是备用文件，每个节点一个 <project folder>/maps/<name>/
• CLI在这四个操作的基础上构建其他所有操作
  • acstack node frontier 列出现在准备开始的事情，最接近最初的目标
  • acstack node walk 按照决策发生的顺序，将整个地图打包成一个简短的新回合
  • 简报总是包括最初的目标，加上你标记为值得进行的任何节点
  • acstack node diagram 绘制一个地图，或一个地图的任何部分，作为一个美人鱼图，下面有一个传说
  • 技能声明和解析节点 update 调用

两个符号链接到达CLI。SessionStart钩子同时维护两者。

• ~/.claude/acstack/bin/acstack 每个技能和代理调用的路径都是固定的吗
  • 因此，代理不依赖于您的shell PATH
  • CLI可以在插件版本冲突、非交互式子shell和新代理上下文中工作
• ~/.local/bin/acstack 是用于打字的 acstack 自己在终端
  • 添加 ~/.local/bin 到你的 PATH 使用它
  • 钩子不在时打印一行提示
  • 没有它，插件中没有任何东西会损坏

如果 acstack 安装克劳德代码后不会运行，请阅读 TROUBLESHOOTING.md． Claude Code会话可以读取它并直接应用修复。

5. 每一个技能

四组，按你伸手的时间排序。

5.1. 实现

对于有开放式决策的工作，用 /acstack:map 第一。

5.2. 规划

5.3. 操作

努力留下的是重要的东西：更新的规范、决策注释和术语表条目。ACStack会丢弃这些节点。

5.4. 设置和支持

6. 每一个代理

当独立解释、审查或平行范围提高信心时，使用代理。

• orchestrator/AGENTS.md 拥有共享的实现规程
• 需要对安全边界、资金、不可逆转的数据更改或未解决的正确性或影响的不确定性进行独立审查
• 单独的测试所有权在选择时保持独立
• 配置的前端门在没有委托检查器的情况下仍然适用

7. 输出样式

该插件提供了一种输出样式。它对每个聊天回复都应用了公司标准。

• Claude Code将样式显示为 acstack:ac-writing-style
• 它适用于 writing 技能的简单语言规则和 visual-docs 技能的金字塔和子弹纪律
• 回复以答案开头，并将90%或更多的内容用项目符号表示
• 每个子弹包含一个句子，结尾没有句号
• 子子弹按照点的需要嵌套，每层缩进四个空格
• 每个词都必须赢得一席之地：没有破折号，没有表情符号，没有夸张，没有没有效果的对比从句

如何开启：

• /acstack:setup 提供两个路径上的样式
  • 在一个新项目中，它来得很晚
  • 这是可选的
  • 在已设置的项目中，它是运行状况检查行
• 技能是这样写的 outputStyle 为你
• 它先问
• 使用 ~/.claude/settings.json 对于每个项目，或者 .claude/settings.local.json 对于这个
• 项目值将覆盖全局值
• 样式应用于 /clear，或在一个新的会话
• 插件永远不会强迫它

这种风格还附带了每回合提醒：

• hooks/ac-writing-style-reminder.sh 运行在每一个提示，并重新注入自己的风格的话
• 内置样式带有 turnReminder 字段，而基于文件的样式不能，因此钩子提供了等效的
• 它发射出两部分直接从 output-styles/ac-writing-style.md
  • “你是谁”，只在最上面几行，这就是角色
  • “寄出之前”的全部内容，这是九项清单
• 它在运行时读取这些部分，因此提醒永远不会偏离样式
• 它在任何其他输出样式下都保持沉默，并且不会向抄本写入任何内容

8. 驱动多个代理的终端工作区

用于在远程计算机上运行多个代理的可选的仅键盘设置。没有它，ACStack工作得很好。

• /acstack:terminal-workspace 安装每个工具并编写每个配置
• 文档/ terminal-workspace.md 给出了确切的配置、每个键和值得了解的陷阱
• 该设置建立在herdr之上，herdr是一个终端多路复用器，它在断开连接后保持每个代理的终端运行
  • 你从你自己的机器上连接 herdr --remote
  • 然后您自己的剪贴板和浏览器到达会话
  • 每个代理都可以获得自己的git工作树，这意味着在自己的分支上有自己的签出
• 然后，h-dash对pull请求进行分类，并对diffnav读取diffs，两者都不离开终端

9. 设计原则

有意义的证据比固定的代理序列更重要。

• 更喜欢实际的测试优先工作，以便在实现之前暴露错误
• 当现有的覆盖率无法捕获错误时，需要对有意义的变更行为进行测试
• 对重构重用足够的覆盖率，并跳过非行为编辑的新测试
• 解释不切实际的测试并披露缺失的回归保护
• 通过提交时规范同步保持文档最新
• 除了未回答的问题，不要建立更多的计划结构
• 为更强的流程保留明确的请求
• 弃用的 workflow.tdd.strict 和 workflow.tdd.orchestrator_strict 布尔值不再控制排序或委托，包括显式 true
  • 这两个键都没有有效的默认值
  • ACStack取消了之前的严格保证
  • ACStack不会自动重写已有的配置
  • 新的安装程序不提供或生成这些密钥

10. 牌照及学分

麻省理工学院． 该设计由四个项目组成。

• OpenSpec - ACStack从OpenSpec派生其CLI
  • OpenSpec是原始工作流下的核心规范引擎
  • 基于地图的概念都源于此：建议、设计、任务、活动规范、变更管理和存档
• 工头人工智能 Taskmaster的任务管理模型启发了编排器模式和代理协调方法
• 真正的工程师必备技能 作者：Matt Pocock——Wayfinder地图，轮询访谈，以及代理简报的持久性规则
  • ACStack的节点图是Wayfinder的直接改编
  • MIT授权，并记录在 THIRD_PARTY_NOTICES
• 额外的灵感来自 超级大国， 德牧 和 规范设备

可选的终端工作区安装（但不捆绑）您驱动的五个工具和它们背后的五个工具。每个人都有自己的执照。

• herdr
• tuicr agavra，它在终端内审查拉取请求
• gh-dash 和 diffnav 由dlvhdr
• δ 由dandavison
• lazygit 由杰西·德菲尔德完成，它在一个键上进行阶段，提交和推进
• 丑角 通过conbeer， SQL编辑器此设置在一个键上打开
• 睚眦 通过sxyazi，文件管理器可以预览光标所在的位置
• mermaid-ascii 由AlexanderGrooff
• 发光 由charmbracelet

tuicr的可选fork编译 agavra / tuicr # 607 由 antonio2368． 它也会编译 agavra / tuicr # 633 其中一个计算尚未提交到上游的修复，都是为这个分支编写的。该构建在默认情况下是关闭的，并且是临时的。

看到 文档/ terminal-workspace.md.