foxclaw 0.1.0 → 0.1.2

package/python/frontend_src/vite.config.js

@@ -0,0 +1,46 @@
+import { execSync } from 'node:child_process'
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { fileURLToPath, URL } from 'node:url'
+
+/* 设置面板底部的版本行照 OpenClaw 写成 git@<sha> · <N 天前>。
+   构建时抓一次 git 信息;没有 git(打包机 / 压缩包)就退回 dev,不让构建失败。 */
+function gitInfo() {
+  try {
+    const sha = execSync('git rev-parse --short HEAD', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+    const ts = Number(execSync('git log -1 --format=%ct', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()) * 1000
+    return { sha, ts: Number.isFinite(ts) ? ts : 0 }
+  } catch {
+    return { sha: 'dev', ts: 0 }
+  }
+}
+
+/* 产物直接写进 frontend/v3/,后端 (StaticFiles(directory=frontend, html=True)) 零改动:
+   /v3/ -> frontend/v3/index.html
+   base 必须是 '/v3/',否则 assets 会打到站点根。 */
+export default defineConfig({
+  base: '/v3/',
+  plugins: [vue()],
+  resolve: {
+    alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) },
+  },
+  define: {
+    __APP_INFO__: JSON.stringify({ git: gitInfo(), built: Date.now() }),
+  },
+  build: {
+    outDir: '../frontend/v3',
+    emptyOutDir: true,
+    target: 'es2022',
+  },
+  server: {
+    port: 5173,
+    /* dev 时把 API 与 WS 透到本地后端,前端代码里一律用相对路径 /api */
+    proxy: {
+      '/api': { target: 'http://127.0.0.1:8000', changeOrigin: true },
+      '/ws': { target: 'ws://127.0.0.1:8000', ws: true },
+      '/planet': { target: 'http://127.0.0.1:8000', changeOrigin: true },
+      /* /knowledge/* 无 /api 前缀:HKC 自带 router 由后端根路径挂载 */
+      '/knowledge': { target: 'http://127.0.0.1:8000', changeOrigin: true },
+    },
+  },
+})

package/python/pyproject.toml

@@ -0,0 +1,265 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "foxclaw"
+version = "0.1.2"
+description = "Foxclaw - a personal agent with memory, built on the HMR memory runtime"
+requires-python = ">=3.11"
+
+# 项目页正文(long_description)。此前缺这一行,PyPI 项目页只显示
+# 「该软件包的作者未提供项目描述」——元数据里没有 Description。中英文各一份,
+# 这里按主要读者选中文版;发布门槛见 tools/release_check.py 的 no_readme /
+# no_long_description 检查(缺正文直接失败,不再允许空白页发出)。
+readme = { file = "README_CN.md", content-type = "text/markdown" }
+
+# 许可:仓库根目录 LICENSE 为 MIT。这里用 { file = "LICENSE" } 而不是 PEP 639 的
+# SPDX 字符串(`license = "MIT"`),因为 build-system 只要求 setuptools>=68,而
+# SPDX 字符串要 setuptools>=77 才会被接受;老写法在 68+ 全部可用,metadata 里同样
+# 带上完整许可全文。
+license = { file = "LICENSE" }
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+]
+
+# 依赖以本表为唯一来源(CI 用 `pip install -e .` 安装,不再手写第二份清单)。
+# 注意:HMR 与 HKC 以 vendor/ 内嵌随包分发、走 sys.path 加载,不是 PyPI 依赖,
+# 故此处**不**声明 hmr/hkc —— 此前声明 hmr>=1.0.0 是空转项(永不从 PyPI 安装)。
+dependencies = [
+    # LLM 提供商(未装/未配 key 时模型路由降级 stub,其余功能照常)
+    "anthropic>=0.25.0",
+    "openai>=1.0.0",
+    # 语义嵌入与向量检索(Harness 语义漂移检测 + HKC 语义搜索)
+    "sentence-transformers>=2.7.0",
+    "numpy>=1.26.0",
+    "scikit-learn>=1.4.0",
+    # HKC 向量索引的硬依赖(不是可选):vendor/hkc/hkc_search/vector_search.py
+    # 的 VectorIndex._init_index() 缺 faiss 时直接 raise ImportError。
+    # 此前只在注释里写「已随本体」而依赖表漏声明 → CI 干净环境装不到,
+    # test_hkc_manifest_reuse 顶层 import 失败(collection error),
+    # Stage B/C 的 vector.size() 断言全红。本机曾手动装过,故一直没暴露。
+    "faiss-cpu>=1.8.0",
+    # API 服务
+    "fastapi>=0.111.0",
+    "uvicorn>=0.29.0",
+    "websockets>=12.0",
+    "pydantic>=2.0.0",
+    # 内置 MCP 服务器(/api/mcp/)+ Skill MCP 客户端(mcp_server.py / skills/mcp_client.py 顶层硬依赖)
+    # 锁 <2.0：mcp 2.x 是大重构(拆出 mcp_types、改 fastmcp/streamable_http/sse 客户端 API、
+    # 换 httpx2)，与本仓库基于 1.x 的调用不兼容；1.27.x 已在 CI 与本地全量回归验证。
+    "mcp>=1.27.0,<2.0",
+    # HTTP 客户端(渠道适配器 + Web 工具)。沿用既有 <0.28 约束
+    "httpx>=0.24,<0.28",
+    # 飞书加密事件解密
+    "cryptography>=41.0.0",
+    # 配置与终端输出
+    "pyyaml>=6.0.0",
+    "python-dotenv>=1.0.0",
+    "rich>=13.7.0",
+]
+
+[project.scripts]
+# 命令名与包名一致(foxclaw),`pip install` 之后直接可用:
+# `pip install -e .` 之后可直接 `foxclaw serve`。
+foxclaw = "foxclaw.cli:main"
+
+[tool.setuptools]
+# vendor/ 里的 HMR 与 HKC 是内嵌运行时(不是 PyPI 依赖)。此前 packages.find 只收
+# foxclaw*,装完 import 得到的是「记忆/知识子系统全部降级为 None」的占位包。
+# 这里把它们真正打进 wheel,并让 package-data 一并带上 LICENSE/JSON 等非 .py 资源。
+include-package-data = true
+
+[tool.setuptools.packages.find]
+# foxclaw 在仓库根;hmr 在 vendor/ 下;hkc_* 在 vendor/hkc/ 下 —— 三个搜索根都要给。
+where = [".", "vendor", "vendor/hkc"]
+include = ["foxclaw*", "hmr*", "hkc_*"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23.0",
+    "ruff>=0.16",
+    "mypy>=1.10",
+    "coverage>=7.5",
+    # 默认回归硬依赖:test_file_ingest / test_domain_import 顶层 import docx/openpyxl,
+    # 缺失即 ModuleNotFoundError。与下方 knowledge-files 重复声明是刻意的——
+    # 此处是"测试视角"(回归必需),下方是"功能视角"(文件摄入)。放 dev 而非 knowledge-files,
+    # 避免为了两个 docx/xlsx 测试连带拖入 pymupdf/ebooklib/mobi 等 PDF/epub 重依赖。
+    "python-docx>=1.1",
+    "openpyxl>=3.1",
+]
+# 浏览器子系统(HIR-Browser)。playwright 是重可选依赖:装了才启用真实浏览器,
+# 未装则 /api/browser/* 优雅降级(available=False)。装后还需 `playwright install chromium`。
+browser = ["playwright>=1.44.0"]
+# Google Gemini provider。model_router 在 FOXCLAW_PROVIDER=google 时才惰性 import
+# google.generativeai;未装则该分支 ImportError(其余 provider 不受影响)。此前只在
+# 文档里写「pip install google-generativeai」,依赖表无对应声明,属 R1 检测出的缺口。
+gemini = ["google-generativeai>=0.8"]
+# 自定义模型 API key 存 OS 凭据库(Windows DPAPI / macOS Keychain / Linux Secret
+# Service)。未装则回退 base64 混淆(防 grep,非加密),见 core/secrets.py。
+keyring = ["keyring>=24.0"]
+# 知识核心(HKC,vendor/hkc)。核心运行时依赖;缺失时 /api/knowledge/* 优雅降级。
+# 真实语义向量另需 sentence-transformers+faiss(已随本体);文件摄入见 knowledge-files。
+knowledge = ["networkx>=3.0", "rank-bm25>=0.2", "aiofiles>=23.0", "requests>=2.31"]
+# HKC 文件摄入(PDF/epub/mobi/docx/xlsx)。仅当要摄入电子书/PDF/Office 文档时需要。
+knowledge-files = ["pymupdf>=1.24", "ebooklib>=0.18", "beautifulsoup4>=4.12", "mobi>=0.3.3", "python-multipart>=0.0.9", "python-docx>=1.1", "openpyxl>=3.1"]
+
+
+# ─────────────────────────────────────────────────────────────
+# 工程化工具链(S1):ruff / mypy / pytest / coverage
+# 策略:首次引入,存量告警显式豁免(只保留死代码/真 bug 硬门),S3 拆分后逐步收紧。
+# ─────────────────────────────────────────────────────────────
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+# 只 lint 主包 + 测试;vendor/ 是内嵌第三方,frontend/skills/tools/bench/evals/examples 非 Python 主包。
+extend-exclude = ["vendor/", "frontend/", "skills/", "tools/", "bench/", "evals/", "examples/"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "B", "I", "UP"]
+# 存量告警显式豁免(风格/现代化类);F 系列(pyflakes 死代码/未定义名)已清零并作为硬门。
+# S3 拆分大文件后,逐条从 ignore 移除以收紧。
+ignore = [
+    "E501",                                              # line-too-long(862 存量)
+    "E701", "E702", "E731", "E741", "E401", "E402",      # pycodestyle 风格
+    "I001",                                              # import 排序(138 存量)
+    "B008", "B034", "B904", "B905",                      # bugbear 非致命(33 存量)
+    "UP006", "UP015", "UP017", "UP031", "UP035", "UP037", "UP041", "UP042", "UP045",  # pyupgrade(143 存量)
+]
+
+[tool.mypy]
+python_version = "3.11"
+ignore_missing_imports = true
+check_untyped_defs = true
+# 渐进式:mypy 存量错误用棘轮门管理(tools/mypy_ratchet.py + tools/mypy_baseline.txt)。
+# 2026-11 实测 673 errors in 90 files,已冻结:CI 中错误数一旦增加即失败,
+# 下降后用 `python tools/mypy_ratchet.py --update` 调低基线。只降不升。
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# S2 迁移完成:全部 76 个测试文件均已迁移为 pytest(无顶层 import 副作用,可安全收集)。
+# 注意:网关/内置MCP/流式限流等少数测试依赖模块级单例(FOXCLAW_GATEWAY、FOXCLAW_MCP_SERVER、
+# _STREAM_LIMITER 均在 import 时按 env 固化),单进程 `pytest tests/` 会让这些单例被首个
+# import 定死、相互污染。故全量执行统一走 tests/run_all.py(每个文件独立子进程
+# `python -m pytest <file> -q` 隔离)。本白名单确保任意单文件可被 pytest 收集/运行。
+python_files = [
+    "test_agent_lifecycle.py",
+    "test_ahs_p2.py",
+    "test_anthropic_tools.py",
+    "test_api.py",
+    "test_api_auth.py",
+    "test_api_host_guard.py",
+    "test_attachments.py",
+    "test_audit_chain.py",
+    "test_audit_sink.py",
+    "test_browser.py",
+    "test_browser_request_guard.py",
+    "test_capabilities.py",
+    "test_channel_signing.py",
+    "test_channel_trust.py",
+    "test_channels.py",
+    "test_cli.py",
+    "test_compaction_toolpair.py",
+    "test_config_layering.py",
+    "test_confirm_nonce.py",
+    "test_context_compaction_wiring.py",
+    "test_dispatch.py",
+    "test_domain_evals.py",
+    "test_domain_import.py",
+    "test_domain_reasoners.py",
+    "test_e2e.py",
+    "test_emb_cache.py",
+    "test_embedding_singleton.py",
+    "test_evals_smoke.py",
+    "test_event_spine.py",
+    "test_evidence_semantic.py",
+    "test_evidence_sse.py",
+    "test_file_ingest.py",
+    "test_finance.py",
+    "test_gateway.py",
+    "test_governance.py",
+    "test_governance_audit.py",
+    "test_governance_middleware.py",
+    "test_hkc.py",
+    "test_hkc_index_build_manager.py",
+    "test_hkc_manifest_reuse.py",
+    "test_hkc_search_event_sync.py",
+    "test_import_path_guard.py",
+    "test_injection_guard.py",
+    "test_integration.py",
+    "test_itinerary.py",
+    "test_kee_semantic.py",
+    "test_kernel.py",
+    "test_learning.py",
+    "test_llm_planner.py",
+    "test_markdown_skills.py",
+    "test_markdown_skills_openclaw.py",
+    "test_mcp_connectors.py",
+    "test_mcp_guardian_discovery.py",
+    "test_mcp_no_memory.py",
+    "test_mcp_policy_gate.py",
+    "test_mcp_server.py",
+    "test_memory_recall.py",
+    "test_metrics.py",
+    "test_multi_chain.py",
+    "test_multimodal.py",
+    "test_negotiation.py",
+    "test_orchestration.py",
+    "test_orchestration_decoupled.py",
+    "test_p3_p5_hardening.py",
+    "test_parallel_dispatch.py",
+    "test_pipeline.py",
+    "test_plan_visible.py",
+    "test_planner.py",
+    "test_policy_gate.py",
+    "test_reasoner.py",
+    "test_release_check.py",
+    "test_resume_checkpoint.py",
+    "test_routing.py",
+    "test_scheduler.py",
+    "test_search.py",
+    "test_semantic.py",
+    "test_sessions.py",
+    "test_settings.py",
+    "test_shadow_learning.py",
+    "test_shared_write.py",
+    "test_envfile.py",
+    "test_secrets.py",
+    "test_skill_taint_gate.py",
+    "test_skills.py",
+    "test_stats_and_events.py",
+    "test_streaming.py",
+    "test_supervisor_pipeline.py",
+    "test_verify_evidence.py",
+    "test_supervisor_triage.py",
+    "test_taint.py",
+    "test_task_stream.py",
+    "test_thinking_sse.py",
+    "test_thinking_stream.py",
+    "test_tool_center.py",
+    "test_tool_parallel.py",
+    "test_tool_params.py",
+    "test_tool_use.py",
+    "test_toplevel_concurrency.py",
+    "test_tracing.py",
+    "test_truth_crystallizer.py",
+    "test_truth_flow.py",
+    "test_url_policy.py",
+    "test_version_sync.py",
+    "test_web_trigger.py",
+]
+addopts = "-q"
+
+[tool.coverage.run]
+source = ["foxclaw"]
+# 全量回归走 run_all.py(每文件独立子进程),coverage 需 parallel 模式:每个子进程各写一份
+# .coverage,最后 `coverage combine` 合并成基线。patch=["subprocess"] 让 coverage run 设置
+# COVERAGE_PROCESS_CONFIG 环境变量,子进程经 coverage 的 sitecustomize(.pth)自动测量,
+# 无需逐个子进程手动包 coverage run(run_all.py 的 subprocess 用 dict(os.environ,...) 继承,链路完整)。
+parallel = true
+patch = ["subprocess"]
+
+[tool.coverage.report]
+show_missing = true

package/python/skills/README.md

@@ -0,0 +1,123 @@
+# Foxclaw Skill 实现 — AHS 标准的参考落地
+
+> 本目录是 **Agent Harness Skills (AHS) v1.0 标准在 Foxclaw 中的具体实现**。
+>
+> - **公用标准**(`/agent-harness-skills/`):厂商无关的抽象规范,定义"应该怎样"。
+> - **本实现**(本目录):把抽象规范**绑定到 Foxclaw 的真实模块**,定义"在 Foxclaw 里实际怎么做"。
+>
+> 两者是"规范 vs 参考实现"的关系。读标准看 `/agent-harness-skills/`,读落地看这里。
+
+---
+
+## 标准 → Foxclaw 实现 的映射
+
+AHS 标准里的每个抽象概念,在 Foxclaw 里都有一个**真实模块**承接。这张表是本实现的核心:
+
+| AHS 抽象概念 | Foxclaw 真实模块 | 文件 |
+|-------------|----------------|------|
+| agent / executor | 五个认知 Agent(主管/财务/行政/办公/助手) | `foxclaw/agents/agents.py` |
+| skill-guard(守门·四阶段权限) | `permission.py::evaluate`(四阶段);V2 后经统一门 **PolicyGate** 归一 | `foxclaw/skills/permission.py` `foxclaw/kernel/policy_gate.py` |
+| 认知护栏(标准之外) | Harness 三维漂移检测(语义/工具/范围) | `foxclaw/harness/harness.py` |
+| skill-memory(记忆) | HMR v2.0 双层记忆适配器 | `foxclaw/core/memory_adapter.py` |
+| 审计追踪 | ThoughtChain 思维链 + HookManager.audit_log(有界) | `foxclaw/core/thought_chain.py` `foxclaw/skills/lifecycle.py` |
+| execution-contract(契约) | `SkillSpec` / `SkillResult` 数据结构 | `foxclaw/skills/__init__.py` |
+| skill-router(路由) | **P1-2 统一 planner** 打分 + 主管分诊 + 管线内 `stage_route`(A) | `foxclaw/planning/planner.py` `foxclaw/skills/pipeline.py` `foxclaw/agents/agents.py` |
+| planner(规划) | **P1-2 确定性拆解** `plan()` + 管线 `stage_plan`(A) | `foxclaw/planning/planner.py` `foxclaw/skills/pipeline.py` |
+| skill-composition(编排) | skill 级 `compose`(+回滚补偿)+ Agent 级 Orchestration(P3 解耦) | `foxclaw/skills/pipeline.py` `foxclaw/orchestration/` |
+| 断路器 / 循环检测 | `CircuitBreaker` + `ToolLoopDetector`(skill 层横切) | `foxclaw/skills/lifecycle.py` `foxclaw/harness/loop_detection.py` |
+| 管线内工具调用(A 方案) | Agent 在认知管线内受 PolicyGate 治理地自主用工具 | `foxclaw/pipeline/cognitive_pipeline.py` `foxclaw/agents/base.py` |
+| 领域 skill | 财务/学习/行程内核 | `foxclaw/finance/` `foxclaw/learning/` `foxclaw/itinerary/` |
+| 模型调用 | 多模型路由(DeepSeek 等) | `foxclaw/core/model_router.py` |
+
+---
+
+## 六个 skill 在 Foxclaw 里的具体落地
+
+### 1. execution-contract → Foxclaw 的 SkillSpec/SkillResult
+
+标准定义了抽象的 SkillInput/SkillOutput。**Foxclaw 用 `foxclaw/skills/__init__.py` 里的
+`SkillSpec` 和 `SkillResult` 落地**:
+- `SkillResult` 字段:`skill_id/success/output/status/message/loop_warning`——**无 trace_node_id**;审计追踪由 ThoughtChain(Agent `_think` 写节点)+ HookManager.audit_log 独立承担,不塞进结果结构
+- `trust_level` → **`SkillSpec.trust_level()` 单一真源**(`permission.evaluate` 直接调用它)按 kind(local/mcp/web_api)推断,SkillAdapter 据此对 mcp 结果降级(原 `permission.TRUST_LEVEL` 双真源 dict 已删,见 V3·P6)
+- 输入校验 → `permission.evaluate` **Stage1** 对 `SkillSpec.params` 执行(经 `invoke → PolicyGate.check_action → evaluate`)
+
+> 差异:标准是 schema 描述;Foxclaw 是可运行的 Python dataclass + 真实校验代码。
+
+### 2. skill-router → 主管 Agent 的分诊
+
+标准定义了三步打分算法。**P1-2 后:该算法(否定过滤 0.8×触发命中 + 0.2×描述匹配)统一在 `foxclaw/planning/planner.py::trigger_route`,主管分派 / `skills/pipeline.py::route` / 管线 `stage_route` 都复用**:
+- 否定词检测 → 统一原语 `planner.is_negated`;主管另有 `_is_meta` 判元问题
+- 主管路由 `SupervisorAgent._route()` 基于 `ROUTING_KEYWORDS`,选定后 `subagents[target].run_task()` 分派
+- **A 方案**:管线内 `stage_route` 用同一 `route` 选主 **skill** 写 `ctx.route`(opt-in,默认关)
+
+> 差异:标准是"选一个 skill_id";Foxclaw 有两条落地——① 主管把任务分派给**真实 Agent 实例**;② 管线内直接选 **skill**。共用 `planning.planner` 打分引擎。
+
+### 3. planner → 主管 Agent 的任务分解
+
+标准定义了结构化执行计划。**P1-2 后:任务拆分由确定性统一 planner 承担**:
+- `skills/pipeline.py::plan` 用 `planning/planner.py` 的 `split_on`/`PARALLEL_TRIGGERS`/`SPLIT_MARKERS` 把任务拆成 Plan/PlanTask(并行/顺序 + 依赖),不再纯靠 LLM 猜结构
+- 管线 `stage_plan` 把任务结构写入 `ctx.plan`(informational)
+- 每子任务经 `route` 映射到 skill / 领域 Agent;assumptions/risks 写入 ThoughtChain 节点
+
+> 差异:标准是 JSON 计划模板;Foxclaw 是**确定性 P1-2 拆结构** + 需要生成性内容时另调真实 LLM + 写入真实思维链。
+
+### 4. skill-composition → 主管编排 + Orchestration 引擎
+
+标准定义了串行/并行/混合编排。**Foxclaw 有两层落地**:
+- **skill 级**:`skills/pipeline.py::compose` 按计划串行执行各 skill,关键路径失败 → 逆序回滚有副作用步骤(`_rollback` compensate/需人工)
+- **Agent 级**:`foxclaw/orchestration/` 跨 Agent 路由(`/api/orchestration/request` → `route_request`,P3 已解耦通用)+ 态势聚合(`/api/orchestration/situation`)
+- 断路器 → **`CircuitBreaker`(`skills/lifecycle.py`,skill 层构件,非 Harness)**
+
+> 差异:标准是编排协议;Foxclaw 是 skill 级 compose(带回滚补偿)+ Agent 级真实消息路由/态势引擎。
+
+### 5. skill-guard → Foxclaw 的 Harness(这是最核心的落地)⭐
+
+标准定义了四阶段权限管线。**四阶段全部实现在 `foxclaw/skills/permission.py::evaluate`**(不是 harness.py——harness 是下面另一回事的三维漂移检测)。V2 后经统一门 `PolicyGate.check_action` 调用:
+
+| 标准的四阶段 | Foxclaw 的实现(全在 `permission.py::evaluate`) |
+|-------------|--------------|
+| Stage1 validate | 校验 `SkillSpec.params` 必填项 |
+| Stage2 deny>ask>allow | `PermissionRules` 规则匹配(deny 铁律不可覆盖) |
+| Stage3 capability | `side_effect`/`destructive`/`external`/readonly,Fail-closed |
+| Stage4 confirm | 有副作用/external/ask 规则且未确认 → 需确认 |
+
+> **V2 统一门(①Step4)**:动作权限(上表)与推理漂移(下方 Harness)归一到 `foxclaw/kernel/policy_gate.py` 的一套 `Verdict` + 统一 `policy.decision.*` 审计事件,底层仍是同一次 evaluate/check,行为逐字不变。
+> **V2 管线内 dispatch(A 方案)**:Agent 在认知管线内自主用工具时,`stage_act` 同样经此四阶段——只读自动、有副作用挂起 `needs_confirmation`(dispatch 前拦截 ⇒ 零副作用)。
+
+**Foxclaw 独有的增强(标准之外的护城河)——注意:这是 Harness,与上面的四阶段权限是两回事:**
+- **三维漂移检测**(语义/工具/范围)→ 这是标准没有的"认知护栏",防 Agent 跑偏
+- **Shadow 校准模式** → 新 Agent 前 N 轮只观测不拦截,自动校准阈值
+- **调度层豁免**(`block_on_semantic` + `IS_ROUTER`)→ 主管豁免语义拦截
+- **Policy 自学习** → 重复漂移模式自动沉淀为规则
+
+> 差异:标准 guard 只管"工具权限";Foxclaw Harness = 工具权限 + **认知漂移检测**(Foxclaw 原创)。
+> 这正是 Foxclaw 作为"认知型 Agent OS"区别于工具型 Agent 的核心价值。
+
+### 6. skill-memory → HMR 双层记忆
+
+标准定义了后端无关的记忆协议。**Foxclaw 用 HMR(`memory_adapter.py`)落地**:
+- 召回 → `_recall_memory(task)` 真实调 HMR 向量检索
+- 注入 → 召回结果写入 Agent 的 messages 上下文
+- 提取持久化 → 办公 Agent 的 `_store_memory` 真实写入 HMR
+- private/shared 双层 → Foxclaw HMR 的真实双层架构(by_agent 分布)
+- embedding → 真实的 TF-IDF 降级 / sentence-transformers / OpenAI embedding
+
+> 差异:标准是"后端无关协议";Foxclaw 是绑定 HMR v2.0 的真实记忆引擎,带衰减和双层。
+
+---
+
+## 一句话总结
+
+> **公用版 AHS 定义"Agent Harness 的 skill 层应该长什么样"(抽象规范);
+> Foxclaw 版把它落到"用 HMR 做记忆、用 Harness 三维漂移做守门、用三 Agent(主管/财务/办公学习)做路由编排、
+> 用 ThoughtChain 做审计"的真实实现上。**
+>
+> Foxclaw 实现不仅满足标准,还在 guard 维度**超出标准**(增加了认知漂移检测这一护城河)。
+
+---
+
+## 对照阅读
+
+- 想了解**标准本身** → 读 `/agent-harness-skills/README_CN.md`
+- 想了解**Foxclaw 怎么实现标准** → 读本文件
+- 想看**实现代码** → 见上方映射表里的真实模块文件

package/python/skills/execution-contract/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: execution-contract
+version: "1.0-foxclaw"
+implements: agent-harness-skills/execution-contract
+description: Foxclaw 实现版契约。把 AHS 标准的 IO 结构落地到 SkillSpec/SkillResult 数据结构。
+bound_modules:
+  - foxclaw/skills/__init__.py (SkillSpec / SkillResult / SkillAdapter)
+  - foxclaw/skills/permission.py (输入校验 Stage1)
+side_effect: read
+trust_level: high
+---
+
+# Execution Contract(Foxclaw 实现版)
+
+> AHS 标准 `execution-contract` 在 Foxclaw 的落地。标准定义 IO schema,本文件定义 Foxclaw 的真实数据结构。
+
+## 标准 → Foxclaw 真实落地
+
+| AHS 标准 | Foxclaw 实现 | 代码位置 |
+|---------|------------|---------|
+| SkillInput | `SkillAdapter.invoke` 的入参 | `skills/__init__.py` |
+| SkillOutput | `SkillResult` dataclass(字段:`skill_id/success/output/status/message/loop_warning`) | `skills/__init__.py: SkillResult` |
+| 审计追踪 | **不在 SkillResult 里**——由 ThoughtChain(Agent `_think` 写节点)+ SkillAdapter 的 `HookManager.audit_log`(有界)双重承担 | `core/thought_chain.py`、`skills/lifecycle.py` |
+| trust_level | **`SkillSpec.trust_level()` 单一真源**(`permission.evaluate` 直接调用)按 kind(local/web_api/mcp)推断,`SkillAdapter` 据此对 mcp 结果降级(原 `permission.TRUST_LEVEL` 已删,见 V3·P6) | `skills/__init__.py`、`skills/permission.py` |
+| 输入校验 | `permission.evaluate` **Stage1** 校验 `SkillSpec.params`(经 `invoke → PolicyGate.check_action → evaluate`) | `skills/permission.py: evaluate` |
+
+## 关键差异
+
+> 标准是 schema 描述;Foxclaw 是可运行的 Python dataclass + 真实校验代码。
+> 注:`SkillResult` **无 `trace_node_id` 字段**——审计追踪独立由 ThoughtChain + HookManager 承担,不塞进结果结构。

package/python/skills/general-assistant/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: general-assistant
+version: "1.0-foxclaw"
+builtin: true
+side_effect: read
+description: 通用助理技能。信息整理、汇总、跨域转述、沟通措辞、待办跟进。原是独立的"助手 Agent",现下放为指令技能,由主管/办公在任何 Agent 命中"整理/汇总/沟通"类任务时自动注入。
+triggers: [整理, 汇总, 汇总一下, 纪要, 邮件, 协助, 沟通, 联系, 转达, 待办, 跟进, 汇报]
+---
+
+# General Assistant(通用助理)
+
+> 原 `AssistantAgent` 下放而成。它不再是一个常驻 Agent —— 谁来干这件事,取决于任务流向哪个
+> Agent(主管统筹、办公学习、财务),技能只负责"怎么干"。
+
+## 什么时候用
+
+- 用户给了一堆散乱材料(多封邮件、多个文件、几段对话),要一个结论或一份纪要;
+- 要把某个领域的产出转述给别的场景(财务结论 → 给同事的说明;学习笔记 → 汇报材料);
+- 需要一段得体的对外措辞(邮件、消息、回复),而不是继续深挖领域内容;
+- 需要把已经聊过的事收成待办清单并跟进。
+
+## 做法
+
+1. **先分清事实与结论**:事实必须有出处(用户原话、文件、工具返回);结论要能指出它由哪几条事实推出。
+2. **一段一段收敛**:材料 → 要点(每条一行) → 归并同类 → 排序(重要/紧急) → 成稿。
+3. **跨域转述保真**:引用数字时带单位和口径(含不含税、哪个时间段),不四舍五入到失真。
+4. **措辞**默认简洁、无套话;对外的邮件给主题行 + 正文,不给"注意事项"说教。
+5. 收尾给一个**可执行**的下一步(谁、做什么、何时),没有就明说"无需跟进"。
+
+## 硬边界
+
+- 材料里没有的事不补;补了要标「推测」。
+- 不把"我建议"写成"已经安排"——没有执行凭据就不声称已完成。
+- 涉及付款、发送、删除等有副作用的动作,交回主管走确认流程,不要在本技能里直接做。

package/python/skills/planner/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: planner
+version: "1.0-foxclaw"
+implements: agent-harness-skills/planner
+description: Foxclaw 实现版规划。把 AHS 标准的任务分解落地到主管 Agent 的 plan 逻辑。
+bound_modules:
+  - foxclaw/planning/planner.py (★ P1-2 统一拆分原语:split_on / PARALLEL_TRIGGERS / SPLIT_MARKERS)
+  - foxclaw/skills/pipeline.py (plan:确定性拆解为 Plan/PlanTask)
+  - foxclaw/pipeline/cognitive_pipeline.py (stage_plan:管线内结构规划)
+  - foxclaw/agents/agents.py (SupervisorAgent._plan_task / run_task)
+side_effect: read
+trust_level: high
+---
+
+# Planner(Foxclaw 实现版)
+
+> AHS 标准 `planner` 在 Foxclaw 的落地。标准定义计划结构,本文件定义 Foxclaw 用主管真实 LLM 生成。
+
+## 标准 → Foxclaw 真实落地
+
+> ⚠️ **P1-2 后:任务拆分(并行/顺序连接词、`split_on`)由确定性统一 planner 承担**——`skills/pipeline.py::plan` 与管线 `stage_plan` 都用 `foxclaw/planning/planner.py` 的 `PARALLEL_TRIGGERS`/`SPLIT_MARKERS`,不再纯靠 LLM 猜结构。
+
+| AHS 标准 | Foxclaw 实现 | 代码位置 |
+|---------|------------|---------|
+| 出执行计划(拆结构) | `plan(task)` 确定性拆成 Plan/PlanTask(并行/顺序 + 依赖) | `skills/pipeline.py: plan` |
+| 拆分原语 | `split_on` + 并行/顺序连接词表 | `planning/planner.py` |
+| 子任务→执行者 | 每子任务经 `route` 映射到 skill / 领域 Agent | `skills/pipeline.py: route`、`agents.py: _route` |
+| 管线内结构化 | `stage_plan` 把任务结构写入 `ctx.plan`(informational) | `pipeline/cognitive_pipeline.py: stage_plan` |
+| assumptions/risks | 写入 Agent 的 ThoughtChain 节点 | `core/thought_chain.py` |
+
+## 关键差异
+
+> 标准是 JSON 计划模板;Foxclaw 是**确定性 P1-2 planner 拆结构**(可并行/顺序 + 依赖)+ 主管对需要生成性内容时另调真实 LLM + 写入真实 ThoughtChain。

package/python/skills/schedule-itinerary/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: schedule-itinerary
+version: "1.0-foxclaw"
+builtin: true
+side_effect: read
+description: 日程行程技能。排期、会议、出差、路线与冲突检查、差旅预算协商。原是独立的"行政 Agent",现下放为指令技能,由办公学习 Agent 在命中日程类任务时注入;行程内核(ItineraryRuntime)仍由代码提供真实路线与冲突数据。
+triggers: [日程, 行程, 会议, 出差, 预约, 日历, 路线, 提醒, 排期, 时间冲突, 几点]
+---
+
+# Schedule & Itinerary(日程行程)
+
+> 原 `AdminAgent` 下放而成。**能力分两层**:真实路线/冲突由 `ItineraryRuntime` 算(代码),
+> 本技能只规定"怎么排、怎么问、怎么不硬闯"。
+
+## 什么时候用
+
+- 用户要给一段时间内的安排(今天/本周/出差几天)定顺序;
+- 要判断"这个会议塞不塞得进去",或两个安排是否撞车;
+- 出差需要路线、耗时、可达性判断;
+- 差旅预算被财务拒了,需要降标准重报。
+
+## 做法
+
+1. **先取约束,再排**:硬约束(截止时间、必须到场、交通耗时)优先于软偏好(上午效率高)。
+2. **冲突必须查,不许假设**:已有行程与待排时间相差 1 小时内即视为可能冲突,标出来让用户定。
+3. **给方案而不是给日程表**:最多 2 个方案,各自代价(早起的代价、多花的时间)写清楚。
+4. **预算协商一轮一降、有下限**:每轮降到上一轮的 75%,不低于原始申请的 60%;到下限就认输
+   交人决定,不贴着红线反复试探。
+5. 输出用时间轴(时间 → 事项 → 地点/通勤),不要散文。
+
+## 硬边界
+
+- 内核没挂载/没有路点时,明说"按估算排",不要把估算讲成实际路线。
+- 不替用户对外承诺时间;排完是"建议",发出邀请属副作用动作,交回主管确认。
+- 查不到(地图/接口失败)就说查不到,不猜通勤时长。

package/python/skills/skill-composition/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: skill-composition
+version: "1.0-foxclaw"
+implements: agent-harness-skills/skill-composition
+description: Foxclaw 实现版编排。把 AHS 标准的多 skill 协作落地到主管编排 + Orchestration 引擎。
+bound_modules:
+  - foxclaw/skills/pipeline.py (★ compose:多 skill 串行执行 + 逆序回滚补偿)
+  - foxclaw/skills/lifecycle.py (CircuitBreaker 断路器)
+  - foxclaw/orchestration/ (跨 Agent 编排:route_request / gather_situation)
+  - foxclaw/agents/agents.py (SupervisorAgent)
+side_effect: read
+trust_level: high
+---
+
+# Skill Composition(Foxclaw 实现版)
+
+> AHS 标准 `skill-composition` 在 Foxclaw 的落地。标准定义编排协议,本文件定义 Foxclaw 用真实编排引擎。
+
+## 标准 → Foxclaw 真实落地
+
+| AHS 标准 | Foxclaw 实现 | 代码位置 |
+|---------|------------|---------|
+| 多 skill 编排 | `compose(plan)` 按计划串行执行各 skill | `skills/pipeline.py: compose` |
+| 失败回滚 | 关键路径失败 → 逆序回滚有副作用步骤(compensate/需人工) | `skills/pipeline.py: _rollback` |
+| 跨 Agent 协作 | `/api/orchestration/request` → `Orchestrator.route_request`(P3 已解耦、通用) | `api.py:571`、`orchestration/` |
+| 全局态势 | `/api/orchestration/situation` → `gather_situation` | `api.py:554`、`orchestration/` |
+| 断路器 | `CircuitBreaker`(三态机,每 skill 独立) | `skills/lifecycle.py: CircuitBreaker` |
+
+## 关键差异
+
+> 标准是编排协议;Foxclaw 有两层:**skill 级** `compose`(多 skill + 回滚补偿,`skills/pipeline.py`)+ **Agent 级** orchestration(跨 Agent 路由/态势,P3 已去领域硬编码)。断路器是 **skill 层**构件(`lifecycle.py`),不属 Harness。