Bridgework 是一个分两阶段使用的技能:第一阶段把用户的技术栈审计成一个 stack 文件,第二阶段在该文件基础上本地提供 Bridgework 画布。画布在本地运行,不连接外部,也不调用任何模型。画布中的每个步骤都可以生成一个提示词(Sources、Ideas 或 Build),供用户粘贴到智能体中。与用户相关的所有数据都保存在 ~/.bridgework/ 中,绝不放在技能目录内;技能自带的演示是合成的。
基本规则
- 扫描是可选的,且需要许可。不得用用户未在本次对话中同意的类别运行 audit.py,应先展示计划。
- 只记名称,不记值。审计记录应用、工具、MCP 服务器和变量名称,绝不读取、打印或存储密钥值,也绝不打开配置文件去读取除服务器名称以外的内容。
- 存在不等于可用。找到表示已安装或已配置,不代表能正常工作;应保持证据等级诚实,除非用户亲自运行过,否则不要标记为端到端验证。
- 不打分。不在任何地方对想象力、新颖性、价值或可行性进行评分。
- 不对外操作。不安装、不登录、不调用 API、不购买、不发布,只在 127.0.0.1 上提供服务。
第一阶段:审计
- 提供演示。首次查看时,在后台运行 scripts/serve.sh demo(端口 4174)并打开。如果用户想直接看自己的技术栈,可跳过。
- 扫描前先询问。运行 python3 scripts/audit.py --plan 并向用户展示每个类别会读取什么;然后用多选题询问允许哪些类别:apps、clis、mcp、models、keys 或 none(仅访谈)。说明 keys 只列出变量名(如 OPENAI_API_KEY),绝不列出其值。
- 只扫描被允许的部分。python3 scripts/audit.py --categories <已同意类别> 会写入 ~/.bridgework/audit.json 并打印摘要;不带 --categories 时不读取任何内容。
- 访谈。按 references/interview.md:确认匹配项,挑选相关的未匹配项,再询问扫描看不到的内容(手机和手表数据、托管账户、其他机器、已知的死胡同)。保持简短:每轮三到四个问题,最多两轮。
- 写入 ~/.bridgework/stack.json。目录中的工具使用 {"use": "<id>"} 并保留审计信号;其他内容成为自定义部件,按 references/stack-format.md 中的类型、领域和位置分类。已知死胡同记为缺口,画成断裂状态,绝不作正常箭头。
第二阶段:构建与提供服务
- python3 scripts/build_stack.py ~/.bridgework/stack.json 会构建 ~/.bridgework/site,先校验全部内容,出错时列出每个问题且不写入任何内容;修正 stack 文件后重新运行。
- scripts/serve.sh 在 http://localhost:4175 提供站点(后台运行)。演示使用 4174,两者保留各自保存的轨迹。
- 为用户打开页面并指出三点:点选两个(或更多)部件并连接;在示例出现前先写下自己的想法;在任意位置按 Prompt(或 Q)获取给智能体的提示词。
- 后续更新时,重新运行审计(再次获得许可)并针对变化做访谈,编辑 stack.json 并重新构建。构建器只替换它自己创建的文件夹。
文件说明
- scripts/audit.py:需同意的只读扫描;--plan 不读取任何内容;--home 和 --root 可指向测试文件夹。
- scripts/catalog.json:约 50 个已知工具,各有只读检测规则和 takes/does/gives 模板;同一未知项反复出现时可在此添加工具。
- scripts/build_stack.py:将 stack 文件构建为站点,带校验;保留内置示例,且仅在其所有部件都存在时解锁。
- scripts/serve.sh:本地服务器,可服务演示、用户站点或任意文件夹和端口。
- references/interview.md:访谈问题、同意措辞以及如何解读审计。
- references/stack-format.md:stack 文件格式及允许的类型、领域、位置和证据等级。
- assets/app/:画布,data/ 中为合成演示;assets/app/INTERACTION.md 说明交互设计。测试:在该目录运行 npm test,并在演示已服务时运行 PORT=4174 sh tests/run-browser.sh(需要 Playwright 和 Chrome)。