boss

Appearance

开发 Quickstart · Day 0 ​

本文档目标: SuperIntern 第一次拿到 vault 后, 跟随本文档逐步操作, 30 分钟内完成本地环境部署 + 烟雾测试通过 + 能跑第一个 Skill。

如果某步卡住超过 5 分钟, 看本文末尾 § 常见问题 或问 CTO。

v3.1.1 (2026-05-27) 状态: V0 5 case 收官 + /boss 用户面命令就位. 装完即可在 Claude Code 内 /boss list 验证。

0. 前提 ​

你已有:

  • macOS 或 Ubuntu 24 开发机
  • 公司 GitLab 账号 + SSH key
  • 1Password 账号 (用于密钥)
  • 飞书账号 (用于接收测试卡片)

Step 1. 拉代码 (2 min) ​

bash
git clone git@${GITLAB_HOST}:judgement/boss-vault.git ~/boss-vault
cd ~/boss-vault
git log --oneline -5     # 应看到 v3.4 锁定 commit

Step 2. 安装系统依赖 (5 min) ​

macOS:

bash
brew install python@3.11 git curl jq

Ubuntu 24:

bash
sudo apt update
sudo apt install -y python3.11 python3-pip git curl jq

验证:

bash
python3 --version    # 应 ≥ 3.11
git --version
jq --version

Step 3. 跑 install.sh (开发模式) (3 min) ​

bash
bash scripts/install.sh --skip-systemd --skip-1password

输出末尾应看到:

✅ 安装完成

如果某步骤报错, 看 § 常见问题。

Step 4. 跑 smoke test (1 min) ​

bash
make smoke

应输出:

=== Skill lint ===
✅ skill_lint PASSED — 无 issue

=== Redact check fixtures ===
17 passed, 0 failed

=== 飞书抓取工具 filter status ===
{...}

✅ smoke test 完成

v2 后 fixture 增至 17 (新增 3 条锚点真名变体, 详见本地 tests/unit/test_redact_check.py)。

接着跑端到端 smoke (T10):

bash
make smoke-e2e

应输出 11 项契约 check 全 ✅ + e2e smoke PASSED。

✓ 如果到这里全 PASS, 你的本地环境已经能写代码。

更多 make targets (v2.7 新) ​

bash
make test                  # pytest tests/ · 应 119 passed, 1 skipped
make attribution-due       # 30/90/365 调度器: 列今天到期 checkpoint
make attribution-check     # 跑 attribution_check.py --dry-run (V0 stub)
make cloud-sync-dry        # cloud_sync.sh feishu-sync target print-only
make cloud-sync-vault-dry  # cloud_sync.sh vault target print-only
make help                  # 全 target 列表

Step 5. 阅读 (你最好在 Day 0 当天读完, 不一定 30 分钟内) ​

按优先级:

  1. CLAUDE.md (550+ 行) — vault 的工程纪律全文, 必读
  2. v3.1 系统设计与开发方案.docx (37 页) — 系统为什么这么设计
  3. v3.1 开发实施手册.docx (59 页) — 你要做什么, 按时间
  4. v3.3 锚点 raw 材料过滤层补丁.docx (18 页) — 飞书抓取工具 集成的最新设计
  5. panels/default.yaml + skills/tian-judgement-orchestrator/SKILL.md — V0 期主入口的具体实现

Step 6. 探索 vault 结构 (5 min) ​

bash
# 看 11 个 Skill
ls skills/

# 看主 orchestrator
cat skills/tian-judgement-orchestrator/SKILL.md | head -30

# 看锚点 raw 材料过滤层 (v3.3 新增)
cat skills/feishu-sync-adapter/SKILL.md | head -50
cat scripts/feishu_sync_filter.py | head -50
cat config/feishu_sync_filter_rules.yaml

# 看 sage-wiki 配置
cat config.yaml

Step 7. 配置 1Password (Day 1 再做, 不阻塞 Day 0) (10 min) ​

bash
# 装 1Password CLI
curl -sSL https://app-updates.agilebits.com/cli/v2/op_install.sh | bash

# 登录
op signin

# 创建 vault
op vault create boss-vault-prod

# 在 1Password GUI 中添加 4 个 item 到此 vault:
#   - anthropic (字段: credential)
#   - lark (字段: app_id, app_secret)
#   - marsdata (字段: credential)

# 验证可以读出
op read "op://boss-vault-prod/anthropic/credential" > /dev/null && echo "✓"

Step 8. 装 Hermes (Day 1, 仅 CTO 或 SuperIntern 在生产机器上做) ​

bash
# 在 prod-01 机器上 (不是开发机)
curl -sSL https://hermes-agent.io/install.sh | bash
hermes --version          # 应 ≥ v0.4

# 初始化
hermes init --workdir ~/.hermes
ln -sfn ~/boss-vault/skills ~/.hermes/skills
ln -sfn ~/boss-vault/.mcp.json ~/.hermes/.mcp.json
ln -sfn ~/boss-vault/.hermes/scheduler.yaml ~/.hermes/scheduler.yaml

# 启动 (生产用 systemd, 开发用 daemon)
op run --env-file=op.env -- hermes start --daemon
hermes status

Step 9. 跑你第一个 Skill (Day 1) (10 min) ​

推荐路径 · /boss slash command (v3.1.1 新) ​

bash
# 1. install /boss skill (symlink 模式, 5 秒)
bash scripts/install_tian_skill.sh

# 2. 在 Claude Code 内验证 (新 session)
#    输入: /boss list
#    应看到 5 个已判断议题 (T11+T19+C3+C4+C5)

# 3. 装好就可以跑判断:
#    /boss "我想判断 X 议题"           # FRESH 模式
#    /boss X --refresh                  # EVOLUTION 模式 (已有 brand 时)
#    /boss X --quick                    # 跳过 WebSearch
#    /boss X --no-judges                # 仅 synthesis 不打分

等价 CLI 路径 (Hermes 上云后, prod 环境) ​

bash
# 列所有 Skill
hermes skills list

# 跑 attribution-checker 干跑
hermes skill run attribution-checker --dry-run

# 跑锚点 raw 材料过滤层 (前提: backups/feishu/ 有内容)
make feishu-sync-filter

# 直接跑 Python pipeline (本地等价于 /boss)
python3 scripts/run_pipeline_local.py "议题描述" --brand <slug>

Step 10. W1 D-Day 5/26 任务清单 ​

W0 准备期 (5/22-5/25) 结束时, 你应该:

  • ✅ 完成 Step 1-7 (本地环境)
  • ✅ git tag v0-prep 存在
  • ✅ 项目主理 + 语料运维 已确认锚点的飞书 open_id (B-1 解决, 见 v3.3 补丁 §6.2)
  • ✅ 语料运维 已部署 飞书抓取工具 + lark-cli OAuth (B-3 解决)

W1 D-Day (5/26 周一) 开始:

  • 阅读 v3.1 开发实施手册 §2.2 (W1 任务分日表)
  • 你的首日任务: 填 cases/C-2026-0001/case.json (某 B2B 客户战略议题, 项目主理 提供模板)
    • 写 industry-trend doctrine 文件 (skills/industry-trend-perspective/references/doctrine/01-pest.md 等)

§ 常见问题 ​

Q1: pip install -r requirements.txt --break-system-packages 失败 "externally-managed-environment" ​

A: 你的 pip 是系统 pip, 加 --break-system-packages 即可。或用 venv:

bash
python3 -m venv ~/.venv-boss
source ~/.venv-boss/bin/activate
pip install -r requirements.txt

Q2: make smoke 报 "skill_lint.py: No module named yaml" ​

A: PyYAML 未装, 跑:

bash
pip3 install pyyaml --break-system-packages

Q3: pre-commit hook 阻断 commit, 但我确认无敏感数据 ​

A: 看 hook 阻断点:

bash
git commit ... 2>&1 | tee /tmp/last-commit.log
cat /tmp/boss-redact.log    # 或 /tmp/boss-skill-lint.log

如果确实是 false positive, 紧急时可:

bash
git commit --no-verify   # 但需 CTO 在飞书群说明原因

Q4: feishu_sync_filter.py 报 "backups/feishu/ 不存在" ​

A: 这是正常的 — W0/W1 期 飞书抓取工具 还没装, backups 目录是空的。filter 在空目录下也能跑, 只是 examined: 0。

Q5: 我修改 SKILL.md 后, sage-wiki 是否会自动重编译? ​

A: ❌ 不会。SKILL.md 在 sage-wiki 的 ignore 列表中 (D7 边界)。修改后只影响 MBA 层。 ✅ 修改 raw/clippings/ 或 anchors/tian/raw/feishu-sync/docs/ 才会触发重编译。

Q6: 我想跑某个 Skill 但 Hermes 还没装 ​

A: Hermes 是生产环境必需的, 开发期你可以直接读 skills/<name>/SKILL.md 思考 prompt 内容, 然后用 Claude API CLI / Claudian (Obsidian 插件) / Claude Code CLI 任一手段跑。

联系 ​

  • 工程问题: CTO (飞书私聊)
  • 业务问题: 项目主理
  • 飞书抓取工具 相关: 语料运维 (飞书抓取工具 维护人)
  • 紧急 (生产宕机): PagerDuty 群

参考:

  • docs/troubleshooting.md — 详细故障排查
  • docs/api-contracts.md — 关键接口契约
  • v3.1 开发实施手册.docx — 完整开发指南

判断力工程化 · Judgement, Engineered · 主站 · GitHub

© 2026 boss-vault contributors