# acstack 中文文档

规范地址：https://npmcn.com/package/acstack/

版本：0\.54\.0
npm 元数据更新时间：2026-11-02T23:26:37.082Z
中文译文更新时间：2026-11-03T01:52:29.480Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/acstack
原文对照：https://npmcn.com/package/acstack/?lang=original
项目主页：https://github.com/ac8318740/acstack#readme
源码仓库：https://github.com/ac8318740/acstack

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：8.6 MB，176 个文件
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：@earendil-works/pi-coding-agent \*
- 首次发布：2026-10-13T03:28:34.095Z
- 最新版本发布：2026-11-02T23:26:36.794Z
- 已发布版本数：27（近 12 个月 27 个）

## 中文简介

具有一流Claude Code和pi支持的代理编码堆栈：技能，编排器说明和验证代理。

## 安装

```sh
npm install acstack
```

也可以使用：`pnpm add acstack`、`yarn add acstack`、`bun add acstack`

## README

# ACStack

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

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

```mermaid
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部分。该文件的其余部分是参考。

| 你想要什么？ | 在 |
| --- | --- |
| 快速入门 | 第一节 |
| 三个命令，以及使用哪一个 | 第二节 |
| 配置一个项目和一台机器 | 第三节 |
| CLI | 第四节 |
| 每一个技能 | 第五节 |
| 每一个代理 | 第六节 |
| 输出样式 | 第七节 |
| 终端工作空间 | 8节 |
| 设计原则 | 9节 |
| 牌照及学分 | 第十节 |

## 1\. 快速入门

ACStack有一流的支持 [克劳德代码](https://claude.com/claude-code) 和 [π](https://pi.dev/).

### 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/` 然后把它们交上去
    -   看到 [项目数据在哪里](https://npmcn.com/package/acstack/docs/config-reference.md#where-project-data-lives) 用于路径、模式和命令
-   迁移旧项目前更新已安装的ACStack工具
    -   停止旧的代理和评论，跑吧 `~/.claude/acstack/bin/acstack project-data migrate`，然后使用更新后的工具重新启动
    -   迁移在没有覆盖或Git索引更改的冲突时中止；跟踪的旧路径成为待处理的删除
-   每当SessionStart钩子检测到一个ACStack项目时，它就会加载编排器指令
-   你的克劳德。Md对于特定于项目的内容保持干净
-   从0.8.0之前的版本升级意味着删除一个过时的版本 `@import` 线(见 [文档/ migrate-0.8.md](https://npmcn.com/package/acstack/docs/migrate-0.8.md)）

### 1.2. 安装在pi上

_相同的项目安装为 [π](https://pi.dev/) 包和 `@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` 只有当一次谈话不能解决所有问题时，才能建立一个地图。_

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

| 状态 | 意义 |
| --- | --- |
| `fog` | 任何你还不能清楚表达的东西 |
| `open` | 准备回答或构建 |
| `claimed` | 有人正在做这件事 |
| `resolved` | 完成 |
| `out-of-scope` | 故意放弃 |

每个节点还记录六件事。

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

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

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

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

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

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

要了解每个步骤的全貌以及它们之间的联系，请阅读 [文档/ workflows.md](https://npmcn.com/package/acstack/docs/workflows.md).

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

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

-   `project.yaml` 在项目文件夹中保存每个项目范围的设置
    -   [文档/ config-reference.md](https://npmcn.com/package/acstack/docs/config-reference.md) 给出每个键，它的值，它的默认值和什么变化
-   `~/.acstack/config.json` 保持9 `host.*` 轴
    -   `/acstack:host` 每台机器一次写入其中的8个，并且 `/acstack:setup` 写第九个
    -   [文档/ dev-setups.md](https://npmcn.com/package/acstack/docs/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](https://npmcn.com/package/acstack/TROUBLESHOOTING.md)． Claude Code会话可以读取它并直接应用修复。

## 5\. 每一个技能

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

### 5.1. 实现

| 技能 | 描述 |
| --- | --- |
| `/acstack:implement` | 构建准备启动的内容，运行第6节中的四个代理，无论是否存在地图 |

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

### 5.2. 规划

| 技能 | 描述 |
| --- | --- |
| `/acstack:map` | 首先回答开放的问题，在第一次运行时构建待办事项图，然后再完成它 |
| `grilling` | 面试本身，询问下一轮可以回答的所有问题，每个问题都有一个推荐的答案（代理调用它）。 |
| `record-context` | 当一个人到达时写下一个决定：一个简短的笔记，一个术语表，两者都写，或者两者都不写（代理调用它） |

### 5.3. 操作

| 技能 | 描述 |
| --- | --- |
| `/acstack:commit` | 提交并更新下面的规范 `<project folder>/specs/` 先从困难开始 |
| `/acstack:archive` | 验证实施规范和当前设计批准，保留审查证据，然后处理临时地图节点 |
| `/acstack:sync` | 在提交之外，从代码更改中更新规范 |
| `/acstack:handoff` | 手动操作到一个可见的代理，一个在自己的窗格中的新代理或一个已经运行的代理，并确认 |
| `/acstack:compact-and-continue` | 锚定会话的承载状态以在压缩中幸存下来，然后在适当的位置继续 |

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

### 5.4. 设置和支持

| 技能 | 描述 |
| --- | --- |
| `/acstack:setup` | 在项目中设置ACStack，并更改已设置的项目的配置方式 |
| `/acstack:host` | 声明此机器的开发设置一次，作为 `host.*` 轴 |
| `/acstack:bootstrap` | 通过阅读现有的代码来编写第一组规范 |
| `/acstack:explore` | 思维伙伴模式，只读 |
| `/acstack:quick-fix` | 带有根本原因分析的结构化bug修复工作流程 |
| `/acstack:pre-commit-review` | 对上次提交以来的所有更改进行深度质量审查 |
| `/acstack:test-conventions` | 测试放置规则和命名约定 |
| `/acstack:code-review` | Linus Torvalds的代码哲学 |
| `/acstack:browser-verify` | 代理-浏览器命令参考、CDP故障排除和选择器策略 |
| `/acstack:bridge` | 设置并操作Playwriter跨设备浏览器桥接 |
| `/acstack:visual-docs` | 编写以图表为导向的文档，并从中派生结构（Minto金字塔） |
| `/acstack:new-worktree` | 在远程基础分支上创建一个git工作树，并在其中继续任务 |
| `/acstack:teardown-worktree` | 退出已完成的工作树，删除它们合并的本地和远程分支，并清理留下来的工作树中的构建输出 |
| `/acstack:terminal-workspace` | 在开发机器上为驱动代理设置一个纯键盘终端 |

## 6\. 每一个代理

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

| 代理 | 角色 |
| --- | --- |
| `test-writer` | 可选的独立于需求和接口的测试 |
| `task-executor` | 实现源代码和测试，除非测试有单独的所有者 |
| `task-checker` | 有界独立评审；仅在分配时才拥有完成检查 |
| `frontend-verifier` | 在最终的前端代码上配置了实时浏览器验证 |

-   `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](https://npmcn.com/package/acstack/docs/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\. 牌照及学分

_[麻省理工学院](https://npmcn.com/package/acstack/LICENSE)． 该设计由四个项目组成。_

-   **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** - ACStack从OpenSpec派生其CLI
    -   OpenSpec是原始工作流下的核心规范引擎
    -   基于地图的概念都源于此：建议、设计、任务、活动规范、变更管理和存档
-   **[工头人工智能](https://github.com/eyaltoledano/claude-task-master)** Taskmaster的任务管理模型启发了编排器模式和代理协调方法
-   **[真正的工程师必备技能](https://github.com/mattpocock/skills)** 作者：Matt Pocock——Wayfinder地图，轮询访谈，以及代理简报的持久性规则
    -   ACStack的节点图是Wayfinder的直接改编
    -   MIT授权，并记录在 [THIRD\_PARTY\_NOTICES](https://npmcn.com/package/acstack/THIRD_PARTY_NOTICES)
-   额外的灵感来自 [超级大国](https://github.com/obra/superpowers)， [德牧](https://github.com/gsd-build/get-shit-done) 和 [规范设备](https://github.com/github/spec-kit)

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

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

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

看到 [文档/ terminal-workspace.md](https://npmcn.com/package/acstack/docs/terminal-workspace.md).

## 常见问题

### acstack 是什么？

具有一流Claude Code和pi支持的代理编码堆栈：技能，编排器说明和验证代理。

### 如何安装 acstack？

在项目目录运行 npm install acstack，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@earendil-works/pi-coding-agent（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 acstack，可以用 npx acstack 直接运行。

### acstack 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/acstack 是否存在。

### acstack 可以商用吗？

acstack 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### acstack 还在维护吗？

最新版本 0\.54\.0 发布于 2026/11/03（今天）；至今共发布 27 个版本，其中过去 12 个月发布了 27 个；首次发布于 2026/10/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。