仓库文件导航
vstack
在任何编码智能体上运行管理者的例行写作工作,并附带它确实做对了的证据。
每周领导力更新、每日项目状态、人才卡片、工作总结、晋升文档:每一件都是同一件事。从保存证据的系统里收集证据,用固定的口吻写作,对照检查清单核对草稿,把它放到由人来按下发送键的地方,记录发生了什么。vstack 把这件事变成一个文件(一个 workflow),在你已经拥有的编码智能体(Claude Code、Codex、Kiro CLI 或 Kiro Crew)上运行它,并且在产物证明它完成之前,绝不承认它已经完成。
一切提到你公司的内容,都存在于第二个私有仓库里,称为 instance。vstack 在运行时读取它,从不包含它;一旦越界,检查就会失败。
- 你能得到什么
- 一次运行如何发生
- 十分钟内安装
- 写下你的第一个 workflow
- 运行它:手动运行与按计划运行
- 一次完成的运行长什么样
- 规则,以及什么在强制执行它们
- 故障排查
- 设计说明
五个词
| 词 | 含义 |
|---|---|
| workflow | 一份例行文档就是一个 JSON 文件:trigger、sources、writer、gate、sink、ledger。workflows/weekly-update.json 就是一个 workflow。vstack 所做的一切,都是对某个 workflow 做的 |
| instance | 保存你公司事实的私有文件夹(同时也是仓库):用哪些工具、哪些文档、哪些渠道、哪些人。vstack 读取它,从不包含它 |
| connector | workflow 请求的一项能力名称( chat.search 、 docs.read )。instance 的 connectors.json 把每个 connector 绑定到真实的 MCP 服务器和工具,因此 workflow 永远不直接指名工具 |
| harness | 运行提示词的编码智能体:Claude Code、Codex、Kiro CLI 或 Kiro Crew |
| run | 一个 workflow 的一次执行:~/.local/state/vstack/runs/ 下的一个产物目录,外加一行 ledger 记录 |
进入内部之后还会再出现三个词:glossary 是写作者会替换使用的公司词汇,context 是 workflow 每次都会读取的常备输入(模板契约、规则、评分标准),brief 则是你用来代替草稿去读的那三行。
example/ 是一个为虚构公司准备的完整 instance。复制它来开始你自己的;检查脚本也用它来证明这些不变量在真实布局上成立。
vstack 中的一切事物都属于三类之一,下面的小节也按这个顺序展开:Define(每次应该发生什么,存在于 instance 中),Run(这一次发生了什么,落在磁盘上),Check(什么会拒绝一个糟糕的定义或一次糟糕的运行,存在于引擎中)。
你能得到什么
| 部件 | 它做什么 | 位置 |
|---|---|---|
| engine | 一个 Python 文件,没有依赖。把 workflow 渲染成提示词,在 harness 上运行它,校验运行目录,维护 ledger,打印计划表和智能体模板 | bin/vstack |
| skills | 写作者(高管更新、人才卡片、工作总结、晋升文档)、批评者( validate-writing )、改写者,以及两个管道类 skill。纯 markdown,采用开放的 Agent Skills 格式 | skills/ |
| harness adapters | 四个智能体各自如何以非交互方式被调用,以及它们从何处读取 skills | harness/README.md 、引擎中的 harness_cmd |
| example instance | 一个为虚构公司准备的完整 instance:connectors、glossary、一个带示例证据的 workflow。复制它来开始你自己的 | example/ |
| evals and checks | 一个九组检查脚本、一个面向 skills 的路由评测、带预期结果的示例证据 | scripts/ 、 evals/ |
一次运行如何发生
你的私有实例 vstack(本仓库) 你的 harness
───────────────────── ──────────────────────── ────────────
workflows/weekly-update.json ─┐
connectors.json ├─▶ vstack run <workflow> --harness claude ─▶ 一个 prompt,绝对路径
glossary.md │ │ │
context/, *.sample.json ─┘ │ 预检:不变量、 ▼
│ skill 副本与 lock 一致 claude -p / codex exec /
│ kiro-cli chat / kirocrew cron
▼ │
~/.local/state/vstack/runs/<workflow>/<harness>-<id>/│
evidence.json diff.md draft.md gate.md brief.md result.json
│ │
│ 契约检查:文件是否都在且格式正确?
▼
ledger/runs.jsonl (每次运行一行,仅追加)
│
▼
撰写框或 [Draft] 文档中的一个草稿。由人按下发送。
harness 运行的 prompt 有八个阶段。每个工作流都是这个循环:
| 阶段 | 发生什么 | 留下什么 |
|---|---|---|
| 1 gather | 调用工作流的 connectors 绑定的工具,缓存优先。只读 | evidence.json,包含来源列表和内容哈希 |
| 2 diff | 与上一次运行的 evidence 对比 | diff.md |
| 3 write | writer skill 将 evidence 转为符合内部文风的草稿。第一行说明使用了哪些来源、哪些不可用 | draft.md |
| 4 gate | validate-writing 给草稿打分,writer 修复每一处被引用的失败项,至少 2 轮、最多 5 轮 | gate.md,第一行为 passes: N |
| 5 land | 草稿进入 sink:撰写框、[Draft] 文档。从不发送 | 落地的路径或 id |
| 5b brief | 三行内容,让忙碌的读者无需打开草稿即可决策 | brief.md |
| 6 record | 一行 ledger、一个结果文件 | result.json、runs.jsonl 中的一行 |
| contract | 引擎回读运行目录。任何缺失或格式错误都会将本次运行标记为 contract_unmet,无论模型声称什么 | meta.json |
两个可选附加项:--second-opinion <harness> 在另一个 agent 上运行独立的评审者并记录其引用发现(从不编辑,从不阻塞),以及 vstack retro 每周回读 ledger 并列出反复出错的地方。
定义:安装并编写你的第一个工作流
十分钟安装
你需要 Python 3.9 或更新版本、git,以及以下至少一项:Claude Code、Codex CLI、Kiro CLI、Kiro Crew。
- 克隆并让每个 harness 读取相同的 skills。
git clone https://github.com/ivikash/vstack ~/github/vstack
V=~/github/vstack/bin/vstack
$V link-skills --canonical ~/github/vstack/skills \
--targets ~/.claude/skills ~/.codex/skills ~/.agents/skills ~/.kiro/skills ~/.kiro/crew/skills \
--skills leadership-writing write-exec-update write-talent-card write-work-summary write-promo-doc \
validate-writing rewrite rewrite-and-validate score-gate gather-evidence
现在每个 harness 目录中都持有指向此 checkout 的符号链接。在这里执行 git pull 会更新所有链接;已存在的真实副本会被移到一旁,而非删除(~/.local/state/vstack/skill-backups)。只传入你拥有的 harness 的目标目录。
- 从示例创建你的实例。一个私有仓库,用你的工作邮箱提交,仅托管在你公司的 git 服务器上。
文章标题:Vstack – 用于管理与领导的 AI
正文:
cp -r ~/github/vstack/example ~/work/my-instance
cd ~/work/my-instance && git init && git config user.email [email protected]
export VSTACK_INSTANCE=~/work/my-instance # or pass --instance DIR on every command
然后按以下顺序编辑:
| 文件 | 改动 |
|---|---|
| connectors.json | 将每个 connector( docs.read 、 chat.search 、 chat.draft 、 ...)绑定到你的 harness 所拥有的 MCP server 和 tool。这是唯一指定真实工具的文件 |
| mcp-servers.json | 这些工具来自的 server。vstack gen-mcp --servers mcp-servers.json --target claude 会打印出每个 harness 配置所需的代码块 |
| glossary.md | 你公司的用语:原则被称为什么、评分量表、层级名称。只改你需要改的键 |
| workflows/program-update.json | 重命名,设置配置值(document id、channel、project),保留 connectors |
| workflows/program-update.sample.json | 用于 dry run 的虚构证据。真实的 section 名称,虚构的值 |
- 证明定义是可靠的。不调用模型,一秒内完成。
$V check # invariants over workflows/
$V map # the estate derived from them: sources, writers, gates, sinks, ledgers, bots
cd ~/github/vstack && scripts/check.sh # the public repo's own checks, including that your instance is private
- Dry run。输入示例证据,输出文件,不发布任何内容,在你所拥有的任意 harness 上运行。
$V run ~/work/my-instance/workflows/program-update.json --harness claude --dry-run
# --harness codex | kiro | kirocrew
当 harness 返回时,该命令会打印 meta.json。查找 "status": "ok" 或 "known_gaps" 以及 "contract": {"met": true}。它指定的运行目录包含所有 artifact。
编写你的第一个 workflow
一个 workflow 就是一个 JSON 文件。以下是示例实例的 workflow,每个字段都带有注释:
{
"id": "program-update", // lowercase-hyphen; names the run dir and ledger
"kind": "writer", // writer | consumer | collector
"component": "program", // partition; "hr" is the private one by default
"trigger": {"cron": "29 8 * * 1-5", "timezone": "UTC", "events": []},
"bot": "ProgramStatus", // the Kiro Crew bot that hosts it (bound on the Schedule page)
"sources": [ // connectors, never tool names; bound through connectors.json
{"connector": "docs.read", "ref": "${config.statusDocId}", "notes": "latest dated entries"},
{"connector": "tasks.list", "ref": "${config.taskProject}", "notes": "owner, due, status, last comment"},
{"connector": "mail.search", "ref": "${config.meetingSummaryQuery}", "notes": "last ${config.lookbackDays} days"},
{"connector": "chat.search", "ref": "${config.discussChannel}", "notes": "status and blockers"}
],
"coverage": {"min_sources": 3}, // check fails a writer that reads fewer sources
"cache": {"key": "program/${config.program}", "ttl_hours": 20},
"writer": {"skill": "write-exec-update"},
"gate": {"skill": "validate-writing", "doc_type": "exec-update",
"min_passes": 2, "max_passes": 5, "coverage_bar": 85,
"second_opinion": "codex"}, // optional independent critic
"sink": {"connector": "chat.draft", "ref": "${config.postChannel}", "dry_run_path": "update.md"},
"ledger": {"file": "program-update.jsonl",
"fields": ["program", "overall_status", "red_sections", "green_by_dates", "open_action_items", "posted_to"]},
// sample evidence: program-update.sample.json beside this file, by default
"config": {"program": "Project Lantern", "statusDocId": "doc-0000", "taskProject": "project-0000",
"meetingSummaryQuery": "\"Meeting summary\" Lantern", "discussChannel": "#lantern",
"postChannel": "#lantern-leadership", "lookbackDays": 14}
}
经验法则:
- 连接器,而非工具。工作流中写 chat.search,connectors.json 中写 slack-mcp / search。改一次工具,所有工作流都跟着变。
- ${config.x} 会在工作流的任何位置被替换,因此 id 和频道只需写在一个块里。
- 三个或更多来源。只有一个来源就是照抄。当你的聊天工具有可询问的助手时,加一个佐证连接器,并把它放进 coverage.require_connectors,让检查强制要求它。
- 写入端永远是草稿。chat.draft、docs.write 写入 [Draft]、mail.draft。会发送的连接器就是 bug。
- 私有工作流(component: "hr")必须指定 workspace,其 ledger 字段不得携带评分、候选人姓名或反馈文本。否则 vstack check 会拒绝。
完整字段参考:schema/workflow.schema.json。用 $V check 校验。
运行:手动与定时
# by hand, live: gathers from real sources, lands a draft, you press send
$V run <workflow> --harness claude
# live gather and gate, but the draft stays a file (for a first look at real evidence)
$V run <workflow> --harness claude --no-publish
# with an independent critic on another agent; findings land in meta.json
$V run <workflow> --harness claude --second-opinion codex
# see the prompt a harness would get, without running anything
$V render <workflow> --harness kiro
# standing schedule: one line per workflow with a trigger
$V gen-cron --harness claude # crontab lines (workflows from $VSTACK_INSTANCE)
$V gen-cron --harness kirocrew # kirocrew cron add commands, with the bot to bind each to
# a Kiro CLI agent template whose tool surface is exactly connectors.json
$V gen-agent --harness kiro > ~/.kiro/agents/vstack-runner.json
# weekly: what happened, what keeps going wrong
$V retro --days 7
定时运行时,cron 行会直接调用 vstack run。对于 Kiro Crew,任务消息会告诉 agent 用它的 shell 渲染工作流并遵循打印出的 prompt,因此每次唤醒都会得到一个新的运行目录,由 agent 自己的 MCP 工具完成收集。
一次完成的运行长什么样
~/.local/state/vstack/runs/program-update/claude-20261115-094200-c0b4fc/
prompt.md the exact prompt the harness received
command.txt the exact command
evidence.json {"gathered_at", "sources": [{"connector","status","items"}], "items": [...], "evidence_hash"}
diff.md what changed since the previous run
draft.md line 1 title, line 2 "Sources: used ...; unavailable ...", then the document
gate.md "passes: 2" then the last pass report, every rule with what it checked
brief.md three lines: what landed, the one fact to look at with its source, where and what to do
update.md the landed copy (dry run and no-publish) or the landed id/URL
result.json {"status": "ok" | "known_gaps" | "failed", "gate_passes": 2, "draft", "brief", "landed"}
gate-second.md (with --second-opinion) "findings: N" then each finding with the offending text quoted
meta.json run id, harness, timings, result, contract {met, unmet[]}, second_opinion
stdout.log what the harness printed
~/.local/state/vstack/ledger/runs.jsonl one line per run, append-only
~/.local/state/vstack/cache/<key>/last-evidence.json
~/.local/state/vstack/retro/<date>.md written by vstack retro
一段来自真实 dry run 的 brief,让你了解它的语气:
PRISM daily exec update (dry run, 11/07 sample data): RED.
Ingestion is RED with no recovery date because the sources give two Hub cut-over targets, 11/05 and 11/19, and the owner owes one date by 11/10 (fixture, test data).
Draft at .../prism-update.md. Reader action: nothing (dry run, not posted).
技能
全部位于 skills/ 下,每个技能一个目录,链接进每个 harness。写入器从不抓取、从不发布:它们只把证据变成文档,别的什么都不做。
| 技能 | 使用场景 | 读取 |
|---|---|---|
| write-exec-update | 面向高管的进度更新:总体结论行,每个工作流一段(RED/YELLOW/GREEN,RED 时附 Green-by),里程碑、风险、行动项、Known Gaps | format.md |
| write-talent-card | 每人的人才评审卡:评级理由与关键交付物章节 | template.md |
| write-work-summary | 结构化工作总结:时间线、任务、挑战、行动、结果、产物 | template.md |
| write-promo-doc | 对照级别 rubric 的叙述式晋升文档,包含真实的 Reasons Not To Promote 章节 | template.md , rubric-TEMPLATE.md |
| validate-writing | 关卡。gate 模式返回通过或不通过,每个失败点都引用原文并给出修复建议;evaluate 模式返回评分报告。从不改写 | checklist.md |
| rewrite | 将提供的文稿按内部规则收紧,保留每个事实与链接,不新增任何内容 | |
| rewrite-and-validate | 同上,然后循环过关卡直到通过,至少两轮 | |
| score-gate | 让任何草稿在固定循环中过关卡,返回最终草稿加一行结果 | |
| gather-evidence | 收集阶段:缓存优先,按连接器,一个 evidence.json ,绝不输出散文 | |
| leadership-writing | 不被调用。存放 house-rules.md(语气:17 条规则,其中 4 条是机械性阻断项)、glossary.md(中性默认值)和 rationalizations.md(12 个借口及反驳,7 个红旗)。每个撰写者和评审者都先读这三份 |
一段话概括语气:先给结论和支撑它的事实,主动语态,不用最高级形容词,不模棱两可,不用破折号或分号,每个主张都绑定证据中的一个产物,每个缺失的事实都标注 (unverified) 或列入 Known Gaps,绝不编造。
检查:规则,以及由什么来执行
没有东西执行的规则只是愿望。docs/RULES.md 把每条规则与其检查配对。检查按运行顺序如下:
| scripts/check.sh 分组 | 失败条件 |
|---|---|
| identity | 此处的提交不是用个人邮箱,或 git config user.email 错误 |
| no-org | 任何公开文件带有公司术语、内部主机、工单、聊天、文档或账号 ID |
| schemas | 某个 JSON 文件无法解析,或示例实例违反不变量 |
| frontmatter | 某个 skill 的 name 不是其目录名的小写连字符形式,或 description 为空或超过 1024 字符 |
| loop | 某个 writer skill 缺少关卡循环(最少 2,最多 5,读取 house-rules) |
| glossary | 某个 skill 引用了未定义的 glossary 键 |
| triggers | 某个 skill 的 description 在 evals/triggers.json(36 个用例,无模型)中无法赢得自己的提示词 |
| rules | docs/RULES.md 指名了不存在的检查或子命令 |
| instance | 设置了 VSTACK_INSTANCE 时:实例位于此检出内、是它的远程,或拥有公开远程 |
以及对实例运行 vstack check:
- 撰写者与关卡从不获取数据:撰写者只收到 evidence.json,别无其他。
- 每个撰写者在写入目标前恰好有一个关卡,min_passes 至少为 2。
- 每个写入目标都记录:没有 ledger 字段的工作流会失败。
- 隐私切割:私有工作流指定私有工作区,其 ledger 字段不得携带评级、候选人、晋升、薪资或反馈文本。
- 每个工作流都有 dry_run_path,因此可以无副作用地运行。
- 每个撰写者至少读取两个来源,覆盖率要求时读取更多。
- 每个来源都是连接器名称,绝不是工具名称。
以及每次运行后的契约:带 sources 和 hash 的 evidence.json、diff.md、带 Sources: 行的 draft.md、通过次数足够的 gate.md、三行的 brief.md、result.json。
命令
文章标题:Vstack – AI for Management and Leadership
正文:
| Command | Does |
|---|---|
| vstack render <workflow> [--harness h] | 打印提示词,不执行任何操作 |
| vstack run <workflow> --harness h [--dry-run] [--no-publish] [--second-opinion h2] [--agent a] [--model m] | 预检、渲染、执行、契约检查、台账记录 |
| vstack check [--instance d] | 对工作流做不变量检查 |
| vstack map [--instance d] [--json] | 从工作流派生出的资产全景:来源、写入方、闸门、汇聚端、台账、机器人 |
| vstack check-run <run-dir> | 对已有运行目录做契约检查 |
| vstack verify-skills --dirs ... --skills ... | 每个指定 skill 在每个 harness 目录中都存在且完全一致 |
| vstack link-skills --canonical d --targets ... --skills ... | 把规范 skill 以符号链接方式链接到每个 harness 目录 |
| vstack gen-cron --harness h [--instance d] | 生成 crontab 行,或 kirocrew cron add 命令(附带要绑定的机器人) |
| vstack gen-agent --harness kiro [--instance d] | 生成一个 Kiro CLI agent 模板,其工具面恰好是 connectors.json |
| vstack gen-mcp --servers f --target h | 为某个 harness 生成 MCP server 配置块 |
| vstack retro [--days n] | 按工作流统计运行次数、契约未命中、闸门通过、反复出现的 Known Gaps |
所有命令都接受 --instance DIR,或读取 $VSTACK_INSTANCE,并据此填充 --connectors、--glossary 和 --workflows。状态存放在 ~/.local/state/vstack 下。
Layout
bin/vstack the CLI, one file, standard library only
schema/ workflow, connectors, ledger (JSON Schema)
skills/ one canonical copy of every skill
harness/README.md the four harnesses: exact command, skills dir, what a run leaves behind
example/ a complete instance for a made-up company: README, connectors.json, glossary.md, mcp-servers.json, workflows/ with sample evidence, vstack.lock
evals/ triggers.json, fixtures/ (synthetic evidence packs the skill evals read), results/
scripts/check.sh the nine check groups
scripts/trigger-eval.py the routing eval
docs/ARCHITECTURE.md why two repos, the layers, the run, the derived map, the scales
docs/RULES.md every rule and its enforcer
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| pre-flight failed (skills) | 某个 harness 目录里有过期副本,或缺少某个 skill。再次运行 vstack link-skills ...,然后运行 vstack verify-skills |
| pre-flight failed (invariants) | 工作流违反了某条规则。vstack check 会逐条打印出来 |
| "status": "contract_unmet" 且 "claimed_status": "ok" | 模型说完成了,但某个文件缺失或格式错误。meta.json 会列出具体是哪个;vstack check-run <dir> 可复现该结果 |
| warning: instance pins vstack X, this checkout is Y | 你更新了 vstack。对每个工作流各做一次 dry run,然后把新的短 SHA 写进实例的 vstack.lock |
| draft says Sources: ... unavailable chat.search | 该连接器在 connectors.json 中未绑定,或该工具没有返回任何内容。修改绑定或 ref,绝不要改草稿 |
| Kiro CLI denies a tool | kiro-cli 3.x 会拒绝任何未在 --trust-tools 中列出的工具;请在 vstack gen-agent 生成的 vstack-runner 模板下运行,或让适配器传入 --trust-all-tools |
| a kirocrew run shows "status": "scheduled" | 正常:该任务异步运行。运行目录会在完成后填充;届时对它运行 vstack check-run |
| check.sh no-org fails on your own text | 该词出现在 denylist 上是有原因的。在公开仓库里换种说法;该术语属于实例 |
Design notes
为什么是两个仓库、每一层各自负责什么、派生地图、隐私边界,以及同一个工作流在四个规模下的形态:docs/ARCHITECTURE.md。已记录的测试运行:evals/results/。