Newshot

Vstack – 用于管理与领导力的 AI

Translation(model translation, not the source's own text)

仓库文件导航

题图
题图

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 读取它,从不包含它
connectorworkflow 请求的一项能力名称( 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四个智能体各自如何以非交互方式被调用,以及它们从何处读取 skillsharness/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 writewriter skill 将 evidence 转为符合内部文风的草稿。第一行说明使用了哪些来源、哪些不可用draft.md
4 gatevalidate-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。

  1. 克隆并让每个 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 的目标目录。

  1. 从示例创建你的实例。一个私有仓库,用你的工作邮箱提交,仅托管在你公司的 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 名称,虚构的值
  1. 证明定义是可靠的。不调用模型,一秒内完成。

        $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
      
  1. 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 Gapsformat.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 个用例,无模型)中无法赢得自己的提示词
rulesdocs/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

正文:

CommandDoes
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

SymptomCause 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 toolkiro-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/。

License

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by HN AI
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗