v0.4 · 2026-05

胖鱼 PEtFiSh 技术白皮书

A. 问题与定位

OpenCode、Claude Code、Cursor、Copilot、Windsurf、Codex、Antigravity——7 个 AI 编程平台，每个都有自己的 skill 格式、路径约定和配置文件。

这导致三个工程问题：

碎片化：同一组织的 skill 要为不同平台手工维护多份副本
无治理：skill 从"某人写了个 SKILL.md"到"进入生产项目"之间，没有格式检查、安全审计、发布门禁
无追踪：没人知道哪些 skill 被真正使用、触发准确率多少、哪些已过时

胖鱼在 skill 层做统一管理：一套 skill 多平台安装，一套流水线从创建到发布全覆盖。不替代任何 AI 平台。

B. 架构总览

┌──────────────────────────────────────────────────────────┐
│                    用户 / CI / CD                          │
│                                                          │
│   /petfish (14 subcommands)    install.ps1 / install.sh  │
│   ─────────────────────────    ─────────────────────────  │
│                    │                      │               │
│            ┌───────┴───────┐      ┌───────┴───────┐      │
│            │  Companion    │      │   Installer   │      │
│            │  (10 skills)  │      │   (4 scripts) │      │
│            └───────┬───────┘      └───────┬───────┘      │
│                    │                      │               │
│            ┌───────┴──────────────────────┴───────┐      │
│            │         Pack Layer (10 packs)         │      │
│            │  pack-manifest.json 统一schema        │      │
│            └───────────────────┬──────────────────┘      │
│                                │                          │
│            ┌───────────────────┴──────────────────┐      │
│            │     Platform Adapter Layer            │      │
│            │     platforms.json (8 platforms)      │      │
│            │     路径映射 + 指令翻译 + 配置合并    │      │
│            └──────────────────────────────────────┘      │
└──────────────────────────────────────────────────────────┘

层	职责	关键文件
用户接口层	`/petfish` 14 个子命令 + 4 个 install 脚本	`petfish.md`, `install.ps1/sh`, `remote-install.ps1/sh`
Companion 层	10 个内置 skill，覆盖 skill 全生命周期	`packs/petfish-companion-skill/.opencode/skills/`
Pack 层	10 个 skill pack，按领域组织	`packs/*/pack-manifest.json`
平台适配层	8 平台路径映射、指令翻译、配置合并	`platforms.json`

C. 平台适配层

核心数据源：platforms.json

platforms.json 是平台适配的唯一数据源。每个平台定义：

{
  "opencode": {
    "display_name": "OpenCode",
    "project": {
      "skills_dir": ".opencode/skills",
      "commands_dir": ".opencode/commands",
      "agents_dir": ".opencode/agents",
      "config_file": "opencode.json",
      "instructions_file": "AGENTS.md"
    },
    "global": { ... },
    "skill_format": "SKILL.md",
    "detect_markers": [".opencode", "opencode.json"],
    "instructions_merge_strategy": "marker_based"
  }
}

8 平台路径映射

平台	Skills 目录	指令文件	检测标记
OpenCode	`.opencode/skills/`	`AGENTS.md`	`.opencode/`, `opencode.json`
Claude Code	`.claude/skills/`	`CLAUDE.md`	`.claude/`, `CLAUDE.md`
Codex	`.agents/skills/`	`AGENTS.md`	`.codex/`
Cursor	`.cursor/skills/`	`.cursor/rules/*.mdc`	`.cursor/`, `.cursorrules`
GitHub Copilot	`.github/skills/`	`.github/copilot-instructions.md`	`.github/copilot-instructions.md`
Windsurf	`.windsurf/skills/`	`.windsurfrules`	`.windsurf/`, `.windsurfrules`
Antigravity	`.agents/skills/`	`AGENTS.md` + `GEMINI.md`	`.agents/`, `GEMINI.md`
Universal	`.agents/skills/`	`AGENTS.md`	(fallback)

指令翻译机制

方法	适用平台	行为
`marker_based`	OpenCode, Codex, Copilot, Windsurf, Antigravity, Universal	用 `<!-- BEGIN/END pack -->` 标记合并，不覆盖用户已有内容
`rename_with_header`	Claude Code, Copilot, Windsurf	复制 AGENTS.md 内容，必要时加平台特定头部
`wrap_as_mdc`	Cursor	将 AGENTS.md 内容包装为 `.mdc` 前置元数据格式

D. Pack 体系

pack-manifest.json 统一 schema

{
  "name": "petfish-companion-skill",
  "version": "0.2.0",
  "description": "AI Worker's Companion...",
  "compatibility": "opencode, claude, codex, cursor, copilot, windsurf, antigravity, universal",
  "skill_count": 10,
  "command_count": 1,
  "agent_count": 0,
  "skills": ["petfish-companion", "marketplace-connector", "skill-author", ...],
  "commands": ["petfish"],
  "agents": []
}

10 个 Pack 的定位

Pack	Alias	定位	Skills	Cmds	Agents
project-initializer-skill	`init`	项目初始化向导	1	1	0
petfish-companion-skill	`companion`	skill 生命周期管理内核	10	1	0
opencode-course-skills-pack	`course`	课程开发全套	15	10	8
repo-deploy-ops-skill-pack	`deploy`	部署与运维	7	0	0
opencode-skill-pack-testcases-usage-docs	`testdocs`	测试用例与文档生成	2	0	0
petfish-style-skill	`petfish`	工程写作风格	1	0	0
opencode-ppt-skills	`ppt`	PPT 设计与制作	2	0	0
trustskills-governance-pack	`trust`	skill 可信度治理	1	0	0
anti-sycophancy-calibration-pack	`calibrate`	反迎合决策校准	1	0	0
context-router-skill	`context`	上下文治理 + 会话管理（28 MCP tools）	1	0	0

E. Companion 内核：10 个内置 Skill

生命周期流水线

mine → author → lint → audit → gate → optimize → eval
  ↓       ↓       ↓      ↓       ↓        ↓       ↓
发现    创建    格式   安全    门禁     优化    评测

+ marketplace-connector (跨市场搜索)
+ skill-usage-tracker   (使用追踪)
+ petfish-companion     (总控调度)

各 Skill 详解

Skill	职责 · 输入 → 输出
petfish-companion	总控调度，动态读取 `packs/*/pack-manifest.json`，路由 `/petfish` 14 个子命令
marketplace-connector	关键词 → 跨 6 个来源（胖鱼仓库、SkillKit、Smithery、Glama、anthropics/skills、GitHub）搜索结果
skill-author	skill 名称+描述 → 完整 SKILL.md + scripts/ + references/ 脚手架
skill-lint	skill 目录 → 100 分制评分+findings（40+ 规则：结构/元数据/内容质量/安全模式）
repo-skill-miner	GitHub 仓库 → 候选 skill 列表（分析结构、README、代码模式）
skill-security-auditor	skill 目录 → 0.0-1.0 风险评分（5 级 severity，检测 shell 注入/凭证/网络/eval）
quality-gate	skill 目录 → PASS/CONDITIONAL/FAIL（编排 lint+audit，松耦合 `find_sibling_script()`）
skill-description-optimizer	skill 目录 → 触发准确率/覆盖面/歧义度优化建议
skill-trigger-evaluator	skill+测试集 → precision/recall 评估报告
skill-usage-tracker	使用事件 → 频率/反馈评分/推荐衰减统计报告（JSON schema）

Catalog 动态加载

catalog_query.py 不使用硬编码的 pack 列表。它通过 _find_packs_root() 从脚本位置向上查找 packs/ 目录，然后遍历所有子目录的 pack-manifest.json：

def _find_packs_root():
    """Walk up from script location to find packs/ directory."""
    current = Path(__file__).resolve().parent
    for _ in range(10):
        candidate = current / "packs"
        if candidate.is_dir():
            return candidate
        current = current.parent
    return None

新 pack 只需放入 packs/<name>/pack-manifest.json，不需要修改任何代码。

F. 质量门禁体系

skill目录
  │
  ├─① Lint (skill-lint)
  │   └─ Score ≥ 80/100? → Continue or FAIL
  │
  ├─② Security Audit (skill-security-auditor)
  │   └─ Risk ≤ 0.5? No CRITICAL? → Continue or FAIL
  │
  ├─③ Metadata Validation
  │   └─ name, version, description valid? → Continue or FAIL
  │
  └─④ Decision
      ├─ ✅ PASS       → 允许发布
      ├─ ⚠️ CONDITIONAL → 需人工确认
      └─ ❌ FAIL       → 必须先修复

Lint 评分规则（100 分制）

起始 100 分，按 finding 扣分：error(-10)、warn(-5)、info(-1)。规则前缀：ST0xx 结构完整性、FM0xx 前置元数据、CT0xx 内容质量、SC0xx 安全模式、PY0xx Python 脚本质量。

Security Audit 评分

风险分 = Σ(finding 权重)，归一化到 0.0-1.0：info=0.0 / low=0.1 / medium=0.3 / high=0.6 / critical=1.0。检测类别：代码执行（subprocess/eval/exec）、硬编码凭证、网络调用、文件系统、markdown 注入。

G. TrustSkills 治理引擎

六个风险维度

维度	权重	含义
`shell`	0.25	shell 执行、子进程调用、高权限工具声明
`network`	0.25	网络访问、外部域名、远程通信范围
`file_write`	0.15	文件写入能力、批量写路径、宽范围写入
`sensitive_data`	0.15	接触密钥、凭证、敏感系统路径、隐私数据
`script_risk`	0.10	脚本内的 file IO、subprocess、network 等行为证据
`persistence`	0.10	持久化副作用，如服务安装、长期状态写入、配置驻留

五级治理动作

级别	阈值	含义
`allow`	≥ 0.00	直接放行
`allow_with_ask`	≥ 0.15	允许执行，先征得用户确认
`sandbox_required`	≥ 0.35	需要沙箱隔离执行
`manual_review_required`	≥ 0.55	必须进入人工复核
`deny`	红线命中	硬拒绝，不走阈值计算

四条红线规则

红线	含义
`subprocess-network-combo`	script 同时具备 subprocess 与 network，可能形成 download-and-exec 路径
`dangerous-system-paths`	读写 `/etc/passwd`、`/etc/shadow`、`/root/.ssh`、`~/.ssh/id_*` 等敏感路径
`sudo-without-approval`	声明 sudo/su，但没有显式 approval_required
`subprocess-os-combo`	script 同时具备 subprocess 与 os 级操作，表明任意命令/高破坏面行为

命中任何一条红线，治理结果直接进入 deny，不走分数阈值。

H. 上下文治理与会话管理（Context Router）

v0.4 引入 context-router pack，通过本地 MCP server 提供话题感知的上下文治理。纯 Python 标准库实现，零外部依赖。

核心能力

能力	说明
话题检测	自动识别用户消息所属话题，支持 CJK 文本，输出关系类型（continue/fork/switch/merge/archive/reset/bridge）和风险等级
污染评分	量化跨话题上下文污染风险（0-100），高于 60 时主动提示用户
上下文隔离	按话题构建 Context Package，隔离不同话题的文件引用、决策和成果
会话管理	话题感知的会话绑定、跨会话恢复、多 Agent 归因、活动查询

28 个 MCP Tools

MCP server 暴露 28 个工具，分四组：

组	工具数	典型工具
话题管理	8	`topic_detect`, `topic_create`, `topic_update`, `topic_merge`
上下文构建	5	`context_build`, `context_get_active`, `contamination_score`
使用追踪	5	`track_file_reference`, `track_decision`, `track_artifact`
会话管理	10	`session_bind`, `session_resume`, `session_query_activity`, `session_recommend_topics`

架构决策

纯标准库：不引入 pydantic、aiohttp 等依赖，降低安装门槛
本地 MCP：通过 opencode.json 中 "type": "local" 配置，由 AI 平台自动启动
7 种关系类型：continue / fork / switch / merge / archive / reset / bridge，覆盖实际工作中的话题演化模式
降级策略：MCP 不可用时静默降级，不阻塞正常工作

I. 反迎合校准（Anti-Sycophancy Calibration）

v0.3 引入 calibrate pack，解决 AI 在评审、方案评估等判断型任务中倾向于顺着用户说的问题。

先中性化问题，再给结论——不直接顺着用户预设表态
先给评分维度，再做判断——至少补一个反方或替代方案
结论与置信度分开表达——证据不足时明确降级
可与其他 skill 组合使用：course-outline-design + calibrate、code-review + calibrate

J. 可扩展性

添加新 Pack

在 packs/ 下创建目录，放入 .opencode/（含 skills/, commands/, agents/），创建 pack-manifest.json，如需 AGENTS.md 合并使用  标记，在 install 脚本中添加 alias。catalog_query.py 自动发现新 pack，无需修改代码。

附录：关键技术决策记录

决策	选择	理由
平台配置	`platforms.json` 单一数据源	避免多处硬编码，新平台只改一个文件
Pack 发现	运行时遍历 `packs/*/pack-manifest.json`	新 pack 零代码接入
安装脚本	PowerShell + Bash 双版本	覆盖 Windows + macOS/Linux
远程安装	`curl \| bash` / `irm \| scriptblock`	零依赖，一条命令
指令合并	marker-based merge	不覆盖用户已有内容
质量门禁编排	`find_sibling_script()`	松耦合，各 skill 可独立更新
trustskills 集成	subprocess 调用外部 CLI	不 vendoring 引擎源码，版本独立升级
Lint JSON 输出	`findings` 字段（非 `issues`）	与 security audit 统一命名
Security JSON 输出	`{"results": [...]}`	便于 gate 解包和聚合
Context Router MCP	纯 Python 标准库	零依赖，任何环境可运行
会话管理	话题绑定而非全局 session	支持多话题并行、跨会话恢复
反迎合校准	组合式 skill，非独立 agent	可叠加到任何评审类 skill，不改变原 skill 逻辑