任务护栏 atshv/Polier

Install · Start ·示例项目 · FAQ ·更新日志 ·版本发布

Polier 以插件形式配合 DeepSeek Harness 使用，也以钩子形式配合 Claude Code 使用。它会先访谈你，写出一页架构说明和任务计划，等你批准后再搭建项目。智能体干活时，它拦截当前任务之外的文件写入，只认有记录的测试运行作为证据，并把每一次尝试、批准和评审轮次都提交成记录。

为什么需要它

| 没有 Polier | 有了 Polier |
| 智能体「顺手修一下」属于别的任务的文件 | 写入守卫拦截任务清单之外的每个文件 |
| 「测试通过了」只是聊天里的一句话 | 只有带退出码和日志哈希的关卡运行记录才算数 |
| 任务没评审就标记完成 | done 需要一次通过的评审、一次交接和关卡记录 |
| 上一个任务还没做完，下一个就开工了 | 依赖未关闭时，in_progress 会被拒绝 |
| 智能体卡住后无限重试，烧光 token | 尝试次数和 token 预算都有上限，到顶就升级处理 |
| 智能体会话里冒出 git push 或 npm publish | 所有角色一律拒绝，发布只在 CI 里由 tag 触发 |
| 事后没人知道当初为什么这么决定 | 运行记录、批准和评审都随任务一起提交 |

工作原理

规则只写一份，放在 core/（Python，仅用标准库）。DeepSeek Harness 插件和 Claude Code 钩子只做一件事：把宿主的事件翻译成对它的调用。tools/ 里的命令行工具在任何 shell 里都能用。

效果预览

每张截图都是参考项目 examples/monorepo-mini 的真实输出。

写入守卫会在智能体碰到任务范围外的第一个文件时拦住它，被拒绝的命令对所有角色都保持拒绝。

检查点会拒绝没有证据支撑的状态，并说明哪条命令能产出证据。

调度计划显示现在可以启动什么、什么在等待以及为什么等、哪些审批还没处理。

调研会把每个锁定版本拿到 npm 和 PyPI 上核对，并把带日期的结论存进 docs/research/。

状态页一眼看全整个项目：阶段、每个任务及其尝试次数、gate 记录、评审结论，以及 token 与预算的对比。render_status.py --html 把它写成一个文件，不需要服务器。图中的 token 数是示例值。

安装

要求：DeepSeek Harness 或 Claude Code、git、Python 3.9+。

git clone https://github.com/atshv/polier.git
dsh plugin --profile web add ./polier

把 web 换成你自己的配置档名，然后重启 harness。要更新，先在克隆目录里跑 git pull，再跑一遍同样的 add 命令，然后重启。

Claude Code： 运行 ./install.sh claude，再把 adapters/claude-code/settings.example.json 里的钩子加到 .claude/settings.json。角色与设置见 adapters/claude-code/README.md。

只要技能、不要插件： 运行 ./install.sh，以后用 ./update.sh。

开始

在空文件夹里开一个新会话，写下：

Plan a new project: a command-line tool that stores my bookmarks locally and finds them again.

Polier 会提问，给出计划等你批准，写好项目文件，再把第一个任务的提示词交给你。从这以后，每个任务都走检查点，而不是靠手工编辑的任务板。

命令

以下命令在 DeepSeek Harness 里使用。Claude Code 改用环境变量 POLIER_ROLE 和 POLIER_TASK。

| 命令 | 作用 |
| /pl lead | 本会话可以写所有内容（规划、看板、合并） |
| /pl worker | 回到当前任务的文件（默认） |
| /pl reviewer | 本会话只能写 reviews/ 下的内容 |
| /pl off | 为本会话关闭守卫 |
| /pl task M03 | 把本会话绑定到一个任务并认领；/pl task 释放认领 |
| /pl status | 显示角色、任务和允许的文件 |
| /pl next | 显示调度计划 |
| /pl policy | 显示当前生效的策略 |
| /pl render | 重新生成 STATUS.md（仅 lead） |

插件还会给智能体提供这些工具：pl_status、pl_gate、pl_scope_check、pl_check、pl_next 和 pl_state。

命令行工具

| 工具 | 用途 |
| tools/check.py | 检查生成的项目：文件、看板、任务简报、预算、阶段、证据、策略、运行记录、审批、漂移 |
| tools/state.py | 对任务状态执行 show、check、set；状态只由它写入 |
| tools/gate.py | 运行单个门禁，锁定共享资源，写入带校验和的记录 |
| tools/approve.py | 对审批记录执行 request、grant、deny、list、check |
| tools/dispatch.py | 调度计划：波次、阻塞任务、冲突、待审批 |
| tools/audit.py | 按策略、运行记录、门禁和评审查看每个任务的合规情况 |
| tools/research.py | 依赖、对照 npm 和 PyPI 检查的版本、带来源的研究笔记 |
| tools/usage.py | 每个任务的 token 用量，对照 budget.max_tokens_per_task |
| tools/render_status.py | 重新生成 STATUS.md；加 --html 还会生成状态页 STATUS.html |
| tools/scope_check.py | 对照任务范围检查改动文件，并检测外部改动 |
| tools/claim.py · slot.py · worktree.py | 每个任务一个活动会话，每个工作树分配端口和测试数据库，任务检出 |
| tools/boundaries.py · contracts.py | 导入边界和契约 schema（配置档 L） |
| tools/release_check.py · smoke.py | 干净的带标签发布，部署后冒烟检查 |
| tools/drift.py · manifest.py | 对比项目本地副本与发布清单 |

项目文件

my-project/
├── ARCHITECTURE.md rules every module follows, one page
├── AGENTS.md commands and rules for agents
├── board.json tasks, dependencies, allowed files, status
├── policy.json limits, approvals, protected paths, denied commands
├── STATUS.md progress, generated, never edited by hand
├── tasks/ briefs for the next 3–5 tasks
├── runs/ one execution record per task: attempts, events
├── reviews/ reviews, gate records, approvals
├── docs/ module map, orchestration, quality, versions, research
└── packages/ services/ apps/ profile L only

Polier 不是什么

- 不是智能体。 它不写代码。它规划工作，并让你已经在用的智能体始终待在这个规划里。
- 不是服务器。 所有内容都是你仓库里的文件，外加几个 Python 脚本。没有东西在后台运行，也不需要数据库或账号。
- 不是沙箱。 守卫拦的是无心之失，不是攻击者；下面列出了它的缺口。
- 不是遥测。 Polier 不向任何地方发送数据。唯一的网络调用是 research.py versions --lookup 的注册表查询，而且只在你运行它时才发生。

守卫不覆盖的范围

守卫让守规矩的智能体不跑偏；它不是沙箱。展开看已知缺口。

守卫让守规矩的智能体不跑偏；它不是沙箱。已知缺口：

- 审批是协作式证据，不是身份认证。 reviews/approvals/AP-NNN.json 没有签名，也不校验身份。谁能写这个文件，谁就能伪造一条已批准的记录，而 shell 写入在守卫之外。把审批提交上去，像审代码一样审它。
- 运行记录可以伪造。 runs/<ID>.json 是文本文件，手动编辑或 shell 写入改它，和改工具一样容易；tools/audit.py 拿它跟看板和证据文件夹比对，而不是跟实际发生的事比对。一个 done 任务如果运行记录被改过，只能以矛盾的形式暴露出来。
- 命令匹配是静态的。 策略里的拒绝模式和仅限主控模式，是在剥掉引号、heredoc、赋值和包装器之后，对 shell 片段做匹配，所以 git push 能被抓到。由变量、eval、解释器或脚本文件拼出来的命令抓不到。
- 策略就是个文件。 谁能写 policy.json，谁就能放宽规则。像保护看板一样保护它，改动要审；守卫只读它，不拥有它。
- 看不见的 shell 写入。 DeepSeek Harness 在写入前只检查自己的文件工具。Claude Code 也检查 Bash，但只看静态扫描命令能看出来的部分（重定向、tee、cp/mv、rm、touch、sed -i、perl -i、dd of=、bash -c）。看不到的有：解释器和脚本（python -c、node -e、./build.sh）、构建工具和包管理器、git 命令（checkout、restore、stash、apply、commit）、xargs、find -exec/-delete、patch，以及带变量、通配符或 $(...) 的路径。这些写入只能靠停止检查兜底。
- 停止检查只看 git status。 已提交的改动、被忽略的文件（.gitignore、.git/info/exclude）和仓库外的文件都看不见。提醒达到 maxStopReminders（DSH）/ POLIER_MAX_STOP_REMINDERS（Claude Code）次后它就放弃，而且在多个任务同时进行、主控或评审会话、没有 git、或它自身失败时都不运行。
- 每次调用都会读看板。 守卫看不见的 shell 写入可以改 board.json（任务状态、scope_write），从而放宽或关掉守卫。停止检查会报告看板变化，但只在一个任务仍处于 in_progress 时；tools/audit.py 会显示运行记录不支持的状态。
- 路径按文本比较。 不跟随符号链接，所以作用域内的链接可以指向作用域外。macOS 和 Windows 的文件系统忽略大小写，比较时也忽略；在区分大小写的文件系统上，两种不同拼写就是两个不同路径。受保护路径的匹配规则用同一套比较。
- 项目从会话文件夹定位。 会话在项目外启动，或在某个 worktree 中启动、而该 worktree 的 board.json 仍把任务标为 pending，都不受保护，直到绑定到任务（DSH 中用 /pl task，Claude Code 中用 POLIER_TASK）。
- 认领是协作式的。 活跃认领会拦住第二个使用认领工具的会话，并指出持有者；从不认领的会话不会被认领本身拦住。认领不是文件锁。
- 门禁记录可以伪造。 reviews/evidence/ 始终可写，智能体可以自己写日志和对应的记录；门禁命令是自由文本。审查者必须把记录的命令与 AGENTS.md 对照。
- 失败时放行。 Python 缺失或钩子出错，写入照常通过。角色存在内存里（DSH）或环境变量里（Claude Code）；能改设置的人就能解除它们。
- 终止警告只是提醒。 kill、pkill 和 killall 从不拦截命令：DSH 发消息，Claude Code 询问。要真正防止停掉别的会话的进程，只有沙箱。
- Claude Code 的特殊之处。 只检查 Write、Edit、MultiEdit、NotebookEdit 和 Bash，不检查 MCP 或其他写文件的工具。Bash 在项目外写 /tmp、临时文件夹或 /dev 不检查；删除 git 未跟踪的文件是允许的（等于撤销一次写入）。

要硬性限制，就把 worker 放进沙箱或容器，只给任务文件的写权限。

FAQ

需要会编程吗？ 不需要。你用大白话描述项目，回答访谈，批准计划。智能体写代码；Polier 让它不偏离计划。

支持哪些智能体？ DeepSeek Harness 用完整插件（/pl 命令和 pl_* 工具），Claude Code 通过两个钩子接入。命令行工具在任何 shell 里都能用，所以其他智能体也能用，只是没有自动防护。

能给已有项目加 Polier 吗？ 可以。访谈有棕地模式，先读仓库（阶段 B），再根据现状规划下一阶段。

token 预算有什么用？ policy.json 里的 budget.max_tokens_per_task 限制单个任务在所有尝试中最多花多少。Claude Code 自动记录用量；到 80 % 工具会警告，到 100 % 任务未经所有者批准不能再次启动。

更新 Polier 会怎样？ 运行中的项目保留自己的 generator_version。changelog 说明每个版本要求项目改什么；在阶段之间更新，绝不要在任务进行中更新。

免费吗？ 免费，MIT 协议。

包结构

| 文件夹 | 内容 |
| core/ | 全部规则：看板、写入守卫、停止检查、门禁、认领、槽位、锁、边界、策略、运行、审批、状态、调度、审计；测试在 core/tests/ |
| adapters/dsh/ | DeepSeek Harness 插件；见 adapters/README.md |
| adapters/claude-code/ | Claude Code 钩子（PreToolUse、Stop） |
| tools/ | 上面那些命令行工具 |
| templates/ | 看板 schema、策略、AGENTS、任务简报、编排、研究笔记、版本、契约、发布、门禁 |
| prompt/ | 流程（generator.md）、编排模型、评分标准、DeepSeek Harness 映射 |
| guide/ | 分步检查清单 |
| examples/ | minimal-cli（配置档 S）和 monorepo-mini（配置档 L）；CI 会检查这两个 |

跑全部测试用 npm test；只跑 core 用 python3 -m unittest discover -s core/tests -t .。

新变化

1.3 为每个任务加上 token 预算（tools/usage.py，在 Claude Code 里自动记录），并新增状态页 STATUS.html。1.2 新增 tools/research.py、一个检查点（任务依赖未完成前先挂起）和自动发布。1.1 加入编排：policy.json、检查点、运行记录、审批、调度和审计。1.0 加入看板 schema 1.0、运行时槽位、独占门禁、认领、工作树和配置档 L。

详细说明和迁移步骤：CHANGELOG.md 和 Releases。

发布

发布是自动的。要发新版本：

1. 在 VERSION 里写上新版本号（例如 1.3.0）。
2. 在 CHANGELOG.md 顶部加一节 ## 1.3.0，写明改了什么、怎么迁移。
3. 把这两个文件推送到 main 或上传到 main。

之后工作流 .github/workflows/release.yml 会同步 package.json 和 tools/manifest.json，跑测试，创建标签 v1.3.0，并发布 GitHub Release，把 changelog 里那一节作为发布说明。如果缺 changelog 小节，它会停下来并给出明确提示，而且绝不会覆盖已有的发布。

许可证

MIT