Skip to content

附录 B. 方法与限制

B.1 完整研究对象确认卡（YAML 形式）

research_subject_confirmation_card:
  research_target:
    rule_used: "star 最多 + 自指 README"
    selected_repository: earendil-works/pi
    user_final_confirmation_input: "https://github.com/earendil-works/pi"

  project_name: pi
  repository_url: https://github.com/earendil-works/pi
  repository_owner: earendil-works
  owner_type: Organization
  project_home: https://pi.dev
  is_official_self_managed: true
  is_fork: false
  is_archived: false
  is_disabled: false
  default_branch: main
  description: "AI agent toolkit: unified LLM API, agent loop, TUI, coding agent CLI"

  license:
    spdx_id: MIT
    name: MIT License
    license_file_present_in_root: true
    license_file_basename: LICENSE

  monorepo_packages_declared_in_root_readme:
    - "@earendil-works/pi-coding-agent"
    - "@earendil-works/pi-agent-core"
    - "@earendil-works/pi-ai"
    - "@earendil-works/pi-tui"
    - "@earendil-works/pi-telemetry"

  discovered_extra_packages_in_monorepo:
    - "@earendil-works/pi-client        (framed CBOR client)"
    - "@earendil-works/pi-server        (experimental)"
    - "@earendil-works/pi-session-backends"
    - "@earendil-works/pi-evals"
    - "@earendil-works/pi-protocol      (CBOR codec + framing)"

  sibling_repos_in_readme:
    - "earendil-works/pi-chat        (Slack/chat 自动化)"

  fixed_snapshot_lock:
    primary: main HEAD
    primary_sha: 2a9b4ebc680053c64e31f635b0b22d5e22564001
    primary_pushed_at: 2026-08-11T16:09:32Z

  cross_reference_anchor:
    latest_release_tag: v0.84.1
    latest_release_sha: 53fa77ccd8a279eb87e92294ef3687b03ff80112
    latest_release_published: 2026-08-07

  stages_already_completed:
    - phase_1_target_identification
    - phase_2_identity_and_snapshot_fix
    - phase_3_existing_knowledge_check (no prior Pi knowledge)
    - phase_4_controlled_copy         (/tmp/pi-snap)
    - phase_5_indexing                (/tmp/pi-inspect)
    - phase_6_modules_and_architecture
    - phase_8_technical_questions     (初步)
    - phase_10_evolution_timeline     (完整)

  stages_pending_user_decision:
    - phase_11_lateral_comparison     (用户决议暂缓)
    - phase_12_publish_to_git_and_cloudflare (必须用户确认)

  explicit_user_overrides:
    - omitted: phase_7_minimal_viable_loop  (用户决议取消)
    - omitted_after_user: phase_11_lateral_comparison

  do_not_execute_until_user_open_the_gate:
    - "git clone (already done under controlled snapshot)"
    - "npm install / pnpm / uv"
    - "run package tests"
    - "run Semgrep / Trivy / Gitleaks"
    - "publish to GitHub / Cloudflare"
    - "promote pending → stable version"

  confirmation_status: gated_for_publication

B.2 行动守则（"诚实标注"清单）

任何对用户提出的内容，必须把以下五个标签区分清楚：

标签 含义 例子
source_fact 源码或官方资料直接支持 "Snapshot-A 锁定 hash = 2a9b4eb..."
documentation_claim 文档断言，未验证 README 说的"本仓库是 Pi agent harness 之家"
inference 推理得到的结论 "scoped transport 设计来自 v0.70 前后"
unknown 客观事实上的未知 "docs(agent) 重构具体影响哪些代码未深读"
conflict 文档与代码冲突 未发现

B.3 已被 SKILL 强制的安全边界

本研究全程未执行：

  • npm install / npm run build / npm run test
  • pre-commit hooks
  • trivy / semgrep / gitleaks
  • 外部网络调用除 api.github.com 与 raw.githubusercontent.com
  • 修改仓库工作树
  • 推送 / 发布
  • 删除 / 清理

B.4 待用户决策（Phase 12）

  1. 是否把整套知识产品沉淀到 GitHub 知识库仓库？（需指定账号与仓库）
  2. 是否部署到 Cloudflare Pages？（必须提供 account / project）
  3. 是否合并兄弟仓库（pi-mono、oh-my-pi、pi-web、edge-pi）作为附录？
  4. /tmp/pi-snap, /tmp/pi-inspect, /tmp/pi-site` 的清理时间？

默认：研究产物（仓库报告页面）保留在 /tmp/pi-site，除非你要求部署到 Cloudflare。