foxclaw 0.1.0 → 0.1.3

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。

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

@@ -0,0 +1,67 @@
+---
+name: skill-guard
+version: "1.0-foxclaw"
+implements: agent-harness-skills/skill-guard
+description: Foxclaw 实现版守门 skill。四阶段权限管线落地在 permission.py;Foxclaw 另有 Harness 三维漂移检测(标准之外的认知护城河);V2 后两者经统一门 PolicyGate 归一。
+bound_modules:
+  - foxclaw/skills/permission.py (★ 四阶段权限管线 evaluate)
+  - foxclaw/kernel/policy_gate.py (★ V2 统一门:权限 + 漂移归一)
+  - foxclaw/harness/harness.py (三维漂移检测,认知护栏)
+  - foxclaw/skills/__init__.py (SkillAdapter.invoke 调 check_action)
+  - foxclaw/agents/base.py (_think → _reasoning_result → check_reasoning)
+side_effect: read
+trust_level: high
+---
+
+# Skill Guard(Foxclaw 实现版)
+
+> 本文件是 AHS 标准 `skill-guard` 在 Foxclaw 的具体实现说明。
+> 标准定义"应该怎样守门",本文件定义"Foxclaw 用哪些真实模块守门"。
+
+## 标准四阶段 → Foxclaw 真实落地
+
+> ⚠️ 四阶段**全部实现在 `foxclaw/skills/permission.py::evaluate`**(不是 harness.py——harness 做的是下面另一回事的三维漂移检测)。`SkillAdapter.invoke` 经统一门 `PolicyGate.check_action` 调用 evaluate。
+
+| AHS 标准阶段 | Foxclaw 实现 | 代码位置 |
+|-------------|------------|---------|
+| Stage1 validate | 校验 `SkillSpec.params` 必填项 | `skills/permission.py: evaluate`(Stage1) |
+| Stage2 deny>ask>allow | `PermissionRules` 规则匹配(deny 铁律不可覆盖) | `skills/permission.py: evaluate`(Stage2) |
+| Stage3 capability | `side_effect` + `destructive` + `external` + readonly 模式,Fail-closed | `skills/permission.py: evaluate`(Stage3) |
+| Stage4 confirm | 有副作用/external/ask 规则且未确认 → 需确认 | `skills/permission.py: evaluate`(Stage4) |
+
+**V2 统一门(①Step4)**:动作权限(上表,`check_action`)与推理漂移(下节 Harness,`check_reasoning`)现归一到 `foxclaw/kernel/policy_gate.py` 的一套 `Verdict`;非 allow 发统一 `policy.decision.*` 审计事件。底层仍是同一次 evaluate/check,行为逐字不变。
+
+**V2 管线内 dispatch(A 方案)**:Agent 在认知管线内自主用工具时,`stage_act` 同样经 `SkillAdapter→PolicyGate.check_action` 走本四阶段——**只读自动、有副作用挂起 needs_confirmation(权限门在 dispatch 前拦截⇒零副作用)**,与直呼工具面同一治理。见 `foxclaw/pipeline/cognitive_pipeline.py`。
+
+## Foxclaw 超出标准的部分(护城河)⭐
+
+标准的 guard 只管"工具权限"。Foxclaw 的 Harness 在此之上**增加了认知护栏**,这是 Foxclaw
+作为认知型 Agent OS 的核心差异:
+
+### 1. 三维漂移检测(标准没有)
+`harness.check(node)` 对每个 ThoughtChain 推理节点计算:
+```
+delta = 0.5·语义漂移 + 0.3·工具漂移 + 0.2·范围漂移
+```
+- 语义漂移:推理内容与 Agent 职责基准的距离(防"财务 Agent 去写诗")
+- 工具漂移:是否超出 ALLOWED_TOOL_CATEGORIES
+- 范围漂移:是否超出任务初始范围
+
+判定:`< warn` PASS / `warn~block` WARN / `≥ block` BLOCK(抛 HarnessBlockedError)。
+
+### 2. Shadow 校准模式(标准没有)
+新 Agent 前 `FOXCLAW_SHADOW_ROUNDS` 轮只观测不拦截,收集真实漂移分布自动校准阈值,
+避免阈值拍脑袋导致误杀。
+
+### 3. 调度层豁免(对应标准的 mode,但 Foxclaw 特化)
+- `IS_ROUTER=True` 的主管 Agent → `block_on_semantic=False`
+- 主管收到任意输入豁免语义拦截(接收一切是其本职),但工具/范围越权仍拦
+- 领域 Agent 保留完整三维拦截
+
+### 4. Policy 自学习(标准没有)
+重复出现的漂移模式自动沉淀为 Policy 规则,Policy 版本递增。
+
+## 与标准的关系
+
+> Foxclaw 的 guard = AHS 标准的工具权限管线 + Foxclaw 原创的认知漂移检测。
+> 满足标准的同时,在认知维度超出标准。

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

@@ -0,0 +1,50 @@
+---
+name: skill-memory
+version: "1.0-foxclaw"
+implements: agent-harness-skills/skill-memory
+description: Foxclaw 实现版记忆 skill。把 AHS 标准的后端无关记忆协议落地到 HMR v2.0 双层记忆引擎。
+bound_modules:
+  - foxclaw/core/memory_adapter.py (HMR 适配器)
+  - foxclaw/agents/base.py (_recall_memory / _store_memory)
+side_effect: read
+trust_level: high
+---
+
+# Skill Memory(Foxclaw 实现版)
+
+> 本文件是 AHS 标准 `skill-memory` 在 Foxclaw 的具体实现说明。
+> 标准定义"后端无关的记忆协议",本文件定义"Foxclaw 用 HMR 怎么实现"。
+
+## 标准三操作 → Foxclaw 真实落地
+
+| AHS 标准操作 | Foxclaw 实现 | 代码位置 |
+|-------------|------------|---------|
+| recall 召回 | `_recall_memory(task)` 调 HMR 向量检索 | `agents/base.py` |
+| inject 注入 | 召回结果写入 Agent messages 上下文 | `agents/base.py` |
+| extract 提取 | `_store_memory()` 写入 HMR | `agents/agents.py: OfficeAgent` |
+
+## Foxclaw 的真实记忆引擎(HMR v2.0)
+
+标准说"后端无关",Foxclaw 绑定的真实后端是 **HMR(Hierarchical Memory Runtime)**:
+
+### 双层架构(对应标准的 private/shared)
+- **私有层**:每个 Agent 只能召回自己的记忆(by_agent 分布)
+- **共享层**:标记 shared 的记忆所有 Agent 可召回(如主管的全局决策)
+- 真实统计:`/api/memory/stats` 返回 private/shared/by_agent/relations
+
+### Embedding(对应标准的相关性计算)
+Foxclaw 实际用三档(自动探测):
+- OpenAI Embedding(配了 openai key)
+- Sentence-Transformers(装了 800MB 包)
+- TF-IDF n-gram(降级默认,无需额外依赖)
+
+### 知识图谱(标准未强制,Foxclaw 增强)
+HMR 维护记忆间的关系图(relations),办公 Agent 入库时自动抽取知识关系。
+
+### 衰减(对应标准的 decay_management)
+HMR 按时间 + 引用频率管理记忆生命周期。
+
+## 与标准的关系
+
+> 标准是抽象协议(任何向量库/KV 都能实现);
+> Foxclaw 是绑定 HMR v2.0 的真实引擎,带双层、知识图谱、三档 embedding。

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

@@ -0,0 +1,35 @@
+---
+name: skill-router
+version: "1.0-foxclaw"
+implements: agent-harness-skills/skill-router
+description: Foxclaw 实现版路由。把 AHS 标准的任务→skill 匹配落地到主管 Agent 的分诊逻辑。
+bound_modules:
+  - foxclaw/planning/planner.py (★ P1-2 统一路由原语:is_negated / trigger_route / keyword_hits)
+  - foxclaw/skills/pipeline.py (route:在 skill 候选上打分)
+  - foxclaw/pipeline/cognitive_pipeline.py (stage_route:A 方案管线内选 skill)
+  - foxclaw/agents/agents.py (SupervisorAgent._route / _is_meta:分派到子 Agent)
+side_effect: read
+trust_level: high
+---
+
+# Skill Router(Foxclaw 实现版)
+
+> AHS 标准 `skill-router` 在 Foxclaw 的落地。标准定义匹配算法,本文件定义 Foxclaw 用主管 Agent 实现。
+
+## 标准 → Foxclaw 真实落地
+
+> ⚠️ **P1-2 后:路由/规划的三步打分原语(否定过滤 0.8×触发命中 + 0.2×描述匹配、`is_negated`、`split_on`)统一收敛到 `foxclaw/planning/planner.py` 单一真源**;主管分派、`skills/pipeline.py::route`、管线内 `stage_route` 都复用它,不再各写一套。
+
+| AHS 标准 | Foxclaw 实现 | 代码位置 |
+|---------|------------|---------|
+| 三步打分 / 选主 | `trigger_route(task, candidates)` 统一引擎 | `planning/planner.py: trigger_route` |
+| 否定词检测 | `is_negated`(统一原语);主管另有 `_is_meta` 判元问题 | `planning/planner.py`、`agents.py: _is_meta` |
+| 触发词匹配 | 候选的 triggers 命中(skill 侧)/ `ROUTING_KEYWORDS`(Agent 侧) | `planning/planner.py`、`agents.py` |
+| 选 skill(A 方案) | 管线内 `stage_route` 用 `skills.pipeline.route` 选主 skill 写 `ctx.route` | `pipeline/cognitive_pipeline.py: stage_route` |
+| 兜底 fallback | 无法归类 → 主管自答(助手/行政已下放为 `general-assistant` / `schedule-itinerary` 技能) | `pipeline/supervisor_stages.py: sv_route / sv_dispatch` |
+| 实际分派 | 主管 `subagents[target].run_task()` | `agents.py: SupervisorAgent.run_task` |
+
+## 关键差异
+
+> 标准是"选一个 skill_id";Foxclaw 有**两条落地**:① 主管把任务分派给一个**真实 Agent 实例**(agents.py);② A 方案下管线内 `stage_route` 直接选 **skill**(opt-in,默认关)。两者共用 `planning.planner` 打分引擎。
+> 元问题(你是谁/能联网吗)由主管自答,跳过分派——Foxclaw 特有。

package/python/tests/conftest.py

@@ -0,0 +1,54 @@
+"""pytest 共享配置:sys.path 注入 + 环境隔离(等价于 run_all.py 的 env 注入)。
+
+关键点:env 必须在**模块级**设置(而非 fixture)。因为 pytest 收集阶段就会 import
+每个测试文件,若 env 晚于 import 设置,测试文件顶层的 `Foxclaw(...)` /
+`TestClient(app)` 会读到未隔离的环境(真实 Key 打外部 API、读真实数据目录等)。
+conftest.py 由 pytest 在收集前加载,故模块级赋值能保证先于任何测试文件 import 生效。
+"""
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+import pytest
+
+_REPO_ROOT = Path(__file__).parent.parent
+if str(_REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(_REPO_ROOT))
+
+_VENDOR_HKC = _REPO_ROOT / "vendor" / "hkc"
+if _VENDOR_HKC.exists() and str(_VENDOR_HKC) not in sys.path:
+    sys.path.insert(0, str(_VENDOR_HKC))
+
+if sys.platform == "win32":
+    import _pytest.pathlib as _ppl
+
+    def _skip_force_symlink(root, target, link_to):
+        return None
+
+    _ppl._force_symlink = _skip_force_symlink
+
+os.environ["FOXCLAW_SKIP_DOTENV"] = "1"
+os.environ["FOXCLAW_SHADOW_ROUNDS"] = "50"
+os.environ["HF_HUB_OFFLINE"] = "1"
+os.environ["TRANSFORMERS_OFFLINE"] = "1"
+os.environ["HKC_EMBEDDING"] = "stub"
+os.environ["FOXCLAW_MCP_SERVER"] = "0"
+os.environ["FOXCLAW_PROVIDER"] = ""
+os.environ["FOXCLAW_MODEL"] = ""
+for _k in ("DEEPSEEK_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY",
+           "GOOGLE_API_KEY", "DASHSCOPE_API_KEY", "FOXCLAW_API_KEY"):
+    os.environ[_k] = ""
+
+os.environ.setdefault("FOXCLAW_DATA_DIR", tempfile.mkdtemp(prefix="foxclaw_test_"))
+
+
+@pytest.fixture
+def test_dir(tmp_path) -> str:
+    """字符串路径的临时目录,替代脚本式测试里的 tempfile.mkdtemp。
+
+    注意不能直接用 pytest 内置 `tmpdir`(旧式 py.path.local,在 Windows + Python 3.14
+    下会触发 WinError 448),故返回 str(tmp_path) 供 `Path()` / `tempfile.mkdtemp(dir=...)`
+    等接受字符串的调用点使用。
+    """
+    return str(tmp_path)