@yottameta/yotta-partner 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 更新日志
 
+## v0.1.1 (2026-09-04)
+
+- 定位声明：元伴 = 跨智能体协作协议的最低公共层；更严的本地铁律优先，冲突以更严者为准。
+- 判定升级：30 秒判定表 + 客观信号（写/删文件、步骤 >3、副作用、跨会话——命中任一至少走「方案」级）+ 灰区判例；拍板阈值按「影响面 + 可回滚性」分三档（直接做 / 先方案 / 完整协议）。
+- 判定痕迹：走完整协议必须先给一行「目标 + 验收」简报；新增用户 10 秒核查清单。
+- 验收模板：坏 vs 好对照示例，验收写成可勾选清单。
+- 记录兜底：每次记录写明落到哪里（状态文件 / 经验条目 / 记忆）；未装元习 / 元忆时明说用项目日志 + 交接锚点兜底，不无声降级。
+- 反模式补两条（表演式协作、隐报不确定）；验证复核加硬要求：未实测 / 未核实结论须显式标注（实测过 / 仅查到文档 / 无法核实）。
+- 文档：SKILL.md / references / README 中英同步；版本 0.1.0 → 0.1.1。
+
 ## v0.1.0 (2026-09-04)
 
 - 定位：元伴（yotta-partner）—— 通用人机协作提效协议技能。

package/README.md

@@ -15,6 +15,8 @@ needed, so simple questions stay simple.</p>
 unreliable output, repeated rework or tasks with side effects.</p>
 <p align="center">No runtime, no daemon, no network calls: the skill is a protocol plus templates that
 any agent can follow on any platform.</p>
+<p align="center">It is the <b>lowest common layer</b> of cross-agent collaboration: any side may keep
+stricter local rules, and the stricter rule wins when they conflict.</p>
 
 <p align="center">
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
@@ -40,6 +42,13 @@ no context, no plan, no verification, no memory across sessions. Yuanban turns t
 It is not a collection of motivational tips. It is a protocol with templates that can be copied
 and executed in any agent.
 
+### Positioning
+
+Yuanban is the **lowest common layer** of cross-agent collaboration protocols. It sets the minimum
+bar for “how to get things done with AI”, so any agent or team can keep its own stricter local rules
+(tighter state-file conventions, stricter release gates, higher evidence requirements). When they
+conflict, the stricter rule wins.
+
 ## Core value
 
 | Advantage | Description |
@@ -47,7 +56,9 @@ and executed in any agent.
 | **Always-load, always light** | Active from session start; a 30-second task gate prevents ceremony on simple questions |
 | **Executable, not inspirational** | A fixed protocol unit: context brief, plan gate, milestones, verification, handover |
 | **Works across agents** | Platform-neutral Markdown; no runtime, daemon or network required |
+| **Lowest common layer** | Cross-agent minimum bar; any side keeps stricter local rules and the stricter one wins |
 | **Fixes the common failure modes** | Missing context, direct action without approval, unverified output, lost session state |
+| **Verifiable, not theatrical** | Acceptance criteria are checkable lists; unverified claims are labeled; evidence is real output |
 | **Focuses on the human** | The user owns direction, judgment and final review; the AI handles execution and memory |
 | **Compounds over time** | Lessons and effective practices are saved for the next collaboration (see yotta-learn) |
 | **Honest boundaries** | Collaboration productivity only; no business, pricing or operations topics |

package/README.zh-CN.md

@@ -12,6 +12,7 @@
 <p align="center">自动应用于复杂/长期任务、跨会话接续、输出不可信、反复返工，或想让与 AI 的合作
 更高效、更可靠。</p>
 <p align="center">无运行时、无守护进程、不联网：它是一份协议 + 模板，任何智能体在任何平台上都能照做。</p>
+<p align="center">它是跨智能体协作协议的<b>最低公共层</b>：任何一侧可保留更严的本地铁律，冲突时以更严者为准。</p>
 
 <p align="center">
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
@@ -35,6 +36,12 @@
 
 它不是鸡汤合集，而是一套可以照抄执行的协议和模板。
 
+### 定位
+
+元伴是跨智能体协作协议的**最低公共层**，只规定「怎么跟 AI 把事做成」的最小公约数。
+任何智能体或团队都可以保留自己更严的本地铁律（更细的状态文件规范、更严的发布闸门、
+更高的证据要求）；两者冲突时，以更严者为准。
+
 ## 核心价值
 
 | 优势 | 说明 |
@@ -42,7 +49,9 @@
 | **常驻但轻量** | 会话开始即生效；30 秒任务判定保证简单问题不被套仪式 |
 | **可执行，不是口号** | 固定协议单元：上下文模板、方案闸门、里程碑、验证、交接 |
 | **跨智能体通用** | 平台中立 Markdown；无需运行时、守护进程或联网 |
+| **最低公共层** | 跨智能体协作的最小公约数；更严的本地铁律始终优先 |
 | **对症常见失败模式** | 不给上下文、未批准直接动手、不验证就信、跨会话全忘 |
+| **可验证，不是表演** | 验收写成可勾选清单；未核实结论显式标注；证据必须是真实输出 |
 | **人的位置清晰** | 用户负责方向、判断和最终复核；AI 负责执行和记忆 |
 | **越用越顺** | 踩坑和有效做法沉淀下来，供下次合作复用（可接元习） |
 | **边界诚实** | 只讲协作提效；不含商业、定价、运营、获客 |

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yotta-partner
-version: 0.1.0
+version: 0.1.1
 description: 元伴 —— 通用人机协作/AI协作提效协议技能（协作协议、AI提效、跨会话、任务交接、工作流）：把「怎么跟 AI 把事做成」固化成可执行协作协议单元（上下文模板：背景/目标/约束/验收；先方案后动手；分步交付；收工锚点；验证复核；经验回流）。触发：用户开始复杂/长期任务、需要人机配合、任务反复中断或下个会话接不上、交付前要验证、想沉淀协作经验时。边界：只讲通用协作提效，不含商业/定价/运营/获客；不替代元引意图澄清、元呈呈现、元忆/元序记录、元习经验沉淀；不保证 AI 输出正确，关键结论由用户复核。
 license: MIT
 metadata:
@@ -18,6 +18,12 @@ metadata:
 把 AI 当副手/搭子，不是答案机：你出方向、判断和真实上下文；AI 出执行、记忆和落地。
 目标是省时间，让你把时间花在判断和创造上。
 
+## 定位（最低公共层）
+
+元伴是跨智能体协作协议的**最低公共层**：只规定「怎么配合 AI 把事做成」的最小公约数。
+任何一侧都可以保留更严的本地铁律（更细的状态文件规范、更严的发布闸门、更高的证据要求），
+两者冲突时以更严者为准——元伴不要求谁放松，只补齐跨智能体统一的部分。
+
 ## 常驻注入（必须，勿跳过）
 
 本技能是**常驻注入**技能：每次新会话开始时自动生效，不依赖用户主动加载。它是协作协议层，
@@ -49,22 +55,44 @@ metadata:
 
 ## 自动应用：30 秒判定
 
-常驻不等于每个回答都长篇大论。收到任务后先按下面规则判定，再决定应用深度：
+常驻不等于每个回答都长篇大论。收到任务后先按下面规则判定，再决定应用深度。
+
+**客观信号（命中任一 → 至少走「方案」级，不得判成直接回答）：**
+
+- 会写 / 删 / 移动文件，或改动现有配置；
+- 步骤明显多于 3 步；
+- 有副作用：发布、推送、授权、动数据、外部通道；
+- 跨会话，或需要留下可恢复的状态。
 
 | 输入特征 | 判定 | 做多少 |
 |---|---|---|
-| 改文件 / 多文件 / 多步骤 / 长任务 | 走完整协议 | 简报 → 方案 → 执行 → 验证 → 记录 |
+| 复杂 / 长期 / 多文件 / 多步骤任务 | 走完整协议 | 简报 → 方案 → 执行 → 验证 → 记录 |
 | 跨会话 / 需要记录项目状态 | 走完整协议 | 简报 → 方案 → 分步交付 → 交接锚点 |
-| 可能有副作用（写 / 删 / 推 / 发布 / 授权） | 先方案后动手 | 方案必须列影响面与回滚 / dry-run |
+| 命中客观信号、会动现有内容但影响面小（改现有代码/配置、删除、发版、动数据） | 先方案后动手 | 方案列影响面与回滚 / dry-run，批准后执行 |
+| 只读 / 新建草稿 / 低风险机械步骤 | 直接做 | 做完一句话报告，不套协议 |
 | 需求模糊，缺目标或验收 | 先补上下文 | 追问 1-3 个关键问题，不全凭猜 |
 | 一次性问答、查一个词、复制改写 | 直接回答 | 不套协议，省用户时间 |
 
+**拍板阈值：按「影响面 + 可回滚性」分三档，别拿「机械」当偷懒借口，也别让真机械的活卡在拍板环节：**
+
+| 档位 | 范围 | 示例 | 动作 |
+|---|---|---|---|
+| 直接做 | 只读 / 新建草稿 / 纯新增无副作用 / 低风险机械步骤 | 查一个词、复制改写、格式化、改 typo、加注释 | 做完一句话报告 |
+| 先方案 | 会改动现有内容，或删除 / 发布 / 动数据 | 改接口签名、删字段、导数据、发版 | 先给方案：影响面 + 回滚 / dry-run |
+| 完整协议 | 复杂 / 长期 / 多步 / 跨会话 | 系统迁移、跨会话任务、反复返工的活 | 五步全走，留判定痕迹 |
+
+**灰区判例（照判例套，不自由心证）：**
+
+- 「改 3 行配置」：改的是现有配置 → 至少走方案级，先给影响面与回滚；行数少不等于机械步骤；
+- 「查一个词，但要落盘归档」：查询只读，但写入动作带副作用 → 至少走方案级，说清写到哪、可否回滚；
+- 「复制改写一段文案」：不改系统状态、步骤 ≤ 3 → 直接做，完事一句话报告。
+
 ## 自动应用顺序
 
 命中「完整协议」后，按顺序执行，不要跳步，也不要串行堆任务：
 
 1. **判定**：按上表决定应用深度；
-2. **简报**：缺背景 / 目标 / 约束 / 验收时先补齐，最坏情况也至少要「目标 + 验收」；
+2. **简报（判定痕迹）**：走完整协议第一步必须输出一行可核查简报，至少含「目标 + 验收」；背景 / 约束缺失时先补齐。这一行让用户看得出协议已启动、验收是什么——可观察 = 可检查 = 可问责；
 3. **方案**：影响面大就先给方案，等用户批准；
 4. **执行**：拆小步，每步给可检查结果；
 5. **验证**：对照验收，贴证据，标注不确定处；
@@ -73,6 +101,18 @@ metadata:
 若项目已装元序（yotta-workflow）/ 元忆（yotta-memory），状态与记忆直接交给它们；
 没装时用轻量兜底：项目内日志 + 自包含交接锚点。
 
+## 用户 10 秒核查
+
+不用逐字读协议，交付时扫这四点，就能看出 AI 有没有按协议走：
+
+1. 走协议前，有没有一行「目标 + 验收」简报？
+2. 动手改文件 / 发布前，有没有先给方案？
+3. 说「完成了」时，有没有贴证据（命令输出 / 文件路径 / 日志）？
+4. 不确定的结论，有没有标注「实测过 / 仅查到文档 / 无法核实」？
+
+四点都过 → 基本守约；任一点缺失 → 先要求补齐，再验收。完整清单见
+`references/collaboration_protocol.md`。
+
 ## 协作协议单元（核心）
 
 每次像样的合作，按下面五步走。详细模板见 `references/collaboration_protocol.md`。
@@ -96,6 +136,13 @@ metadata:
 验收：怎么算做对？
 ```
 
+验收要写成**可勾选、可检查**的清单，不是「做好」「完成」。对照示例：
+
+- ❌ 验收：把功能做完、没问题。
+- ✅ 验收：`python selftest.py` 全绿；边界 X / Y / Z 已覆盖；输出文件能在 `deliverables/` 打开预览；未改动清单外的任何文件。
+
+写不出可勾选项，说明「做对」还没想清楚，先别动手。
+
 ## 先方案后动手
 
 除低风险机械步骤外，AI 不应默认直接改文件或执行命令。
@@ -109,6 +156,9 @@ metadata:
 
 你拍板后，AI 才开始执行；执行中发现问题，先停下说明，再决定继续或改路。
 
+「低风险机械步骤」的边界见上方「拍板阈值」：只读 / 新建草稿 / 改动极小且可回滚的活可先做；
+会动现有内容或不可逆的，一律先方案。
+
 ## 分步交付
 
 - 一个会话只交付一个里程碑，做完即收口；
@@ -122,15 +172,17 @@ metadata:
 
 - 验收标准逐条过，不是笼统说「完成了」；
 - 关键结论可溯源（文件/命令/日志/引用）；
-- 测试、校验、dry-run 等证据已核对输出；
+- 测试、校验、dry-run 等证据已核对输出；没跑过的就说没跑，不编造、不摆拍；
 - 未做越权事项（超出授权范围、未批准的写/推/删）；
-- 不确定结论如实标注，不把猜测当事实。
+- 未实测 / 未核实的关键结论，必须显式标注：实测过 / 仅查到文档 / 无法核实，不把猜测当事实。
 
 ## 记录与经验回流
 
-- 长期/跨会话任务：更新项目状态文件，生成交接锚点（模板见协议文档）；
-- 踩过的坑、有效做法：写入项目的 `.learnings/` 或等价经验目录；
+- 长期/跨会话任务：更新项目状态文件，生成交接锚点（模板见协议文档），并说明更新了哪个文件；
+- 踩过的坑、有效做法：写入项目的 `.learnings/` 或等价经验目录，写明条目位置；
 - 若已安装元习（yotta-learn），用它的 `log` 流程沉淀；若已安装元忆（yotta-memory），重要事实用 `remember` 落盘；
+- **每次记录都写明「本次落到哪里」**：哪个状态文件、哪条经验条目、哪条记忆——不写一句「已记录」就结束；
+- **未装元习 / 元忆时明说兜底**：本次用项目日志 + 交接锚点记录，装后可升级；不无声降级、不让人误以为已沉淀；
 - 这些记录只有经过用户同意才进入永久记忆，不默认收集私密信息。
 
 ## 反模式
@@ -142,6 +194,8 @@ metadata:
 | 不验证就信输出 | 走验收、证据、复核三步 |
 | AI 只顾输出「像样」 | 要求可溯源、可复现 |
 | 不记录导致下会话全忘 | 留状态与交接锚点 |
+| AI 表演式协作：方案、验证都演给你看，证据是编的 | 要求真实输出与可回放步骤；没跑过就明说没跑 |
+| AI 隐报不确定：把猜测当事实输出 | 未实测 / 未核实必须显式标注：实测过 / 仅查到文档 / 无法核实 |
 
 ## 边界
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-partner",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Yuanban (元伴) — a human-AI collaboration protocol skill: a repeatable collaboration unit with a context brief (background / goal / constraints / acceptance), plan-first gate, milestone delivery, verification, handover anchors and experience reuse. Triggers when users start a complex or long-running task, keep losing context between sessions, or want a trustworthy way to work with AI. Boundaries: collaboration productivity only, no business/pricing/operations topics; not a substitute for intent clarification, presentation, memory or learning-loop skills; final conclusions are verified by the user.",
   "license": "MIT",
   "keywords": [

package/references/collaboration_protocol.md

@@ -3,6 +3,9 @@
 本文件是元伴（yotta-partner）的执行内核。它是一个可重复使用的协作协议：
 上下文简报 → 方案闸门 → 分步交付 → 验证复核 → 交接与经验回流。
 
+定位：元伴是跨智能体协作协议的**最低公共层**，只规定协作的最小公约数；任何一侧更严的
+本地铁律优先，两者冲突时以更严者为准。
+
 ## 一、上下文简报模板
 
 开始任务前，先填这份简报。缺字段时 AI 应追问，而不是猜测；用户填不全时至少要给
@@ -26,6 +29,17 @@
 - 怎么算做对？（可勾选清单）
 ```
 
+**验收写法（坏 vs 好）：**
+
+- ❌ 验收：把功能做完、没问题。
+- ✅ 验收：
+  - `python selftest.py` 全绿；
+  - 边界 X / Y / Z 已覆盖；
+  - 输出文件能在 `deliverables/` 打开预览；
+  - 未改动清单之外的文件。
+
+验收标准要能**逐条打勾**；写不出可勾选项，说明「做对」还没定义清楚，先别动手。
+
 ## 二、先方案后动手
 
 复杂或可能产生副作用的任务，默认先出方案再执行：
@@ -36,6 +50,17 @@
 4. AI 列出待确认问题，不等用户开口就主动问；
 5. 用户批准后开始；单步低风险机械操作可先做，但要在方案里说明。
 
+**拍板阈值：按「影响面 + 可回滚性」分三档，决定哪些要等批准：**
+
+| 档位 | 范围 | 示例 | 动作 |
+|---|---|---|---|
+| 直接做 | 只读 / 新建草稿 / 纯新增无副作用 / 低风险机械步骤 | 查一个词、复制改写、格式化、改 typo、加注释 | 做完一句话报告 |
+| 先方案 | 会改动现有内容，或删除 / 发布 / 动数据 | 改接口签名、删字段、导数据、发版 | 方案列影响面 + 回滚，批准后执行 |
+| 完整协议 | 复杂 / 长期 / 多步 / 跨会话 | 系统迁移、跨会话任务、反复返工的活 | 简报 → 方案 → 执行 → 验证 → 记录 |
+
+「机械」不是偷懒挡箭牌：只有改动极小且可回滚（如 git diff 可恢复）的才归「直接做」；
+会动现有内容或不可逆的，一律先方案。
+
 如果 AI 已经直接动手：
 
 - 停下当前动作；
@@ -55,16 +80,19 @@
 
 - [ ] 验收标准逐条满足，不是笼统说「完成了」；
 - [ ] 关键结论可溯源：代码 / 命令 / 日志 / 引用 / 截图？
-- [ ] 测试、校验、dry-run 已运行，且输出已核对；
+- [ ] 测试、校验、dry-run 已运行且输出已核对；没跑过的就说没跑，不编造、不摆拍；
 - [ ] 没有越权动作：未批准的文件写、删除、推送、发布；
-- [ ] 不确定的地方如实标注，没有把猜测写成事实；
+- [ ] 未实测 / 未核实的关键结论已显式标注：实测过 / 仅查到文档 / 无法核实；
 - [ ] 若任务跨会话，已更新状态并留下交接锚点。
 
-用户复核时，可以只做三件事：
+**用户 10 秒核查（不用逐字读协议）：**
+
+1. 走协议前，有没有一行「目标 + 验收」简报？
+2. 动手改文件 / 发布前，有没有先给方案？
+3. 说「完成了」时，有没有贴证据（命令输出 / 文件路径 / 日志）？
+4. 不确定的结论，有没有标注「实测过 / 仅查到文档 / 无法核实」？
 
-1. 看验收清单是否真过；
-2. 抽样看不理解的关键结论，要求给证据；
-3. 对高风险动作要求 AI 先 dry-run 或回滚方案。
+四点都过 → 基本守约；任一点缺失 → 先要求补齐再验收。高风险动作再单独要求 dry-run 或回滚方案。
 
 ## 五、交接锚点模板
 
@@ -101,8 +129,9 @@
 ## 六、经验回流
 
 - 有效做法、踩坑原因、修复方法，先写进项目内日志或 `.learnings/`；
-- 若已安装元习（yotta-learn），用它的条目协议沉淀，格式统一可检索；
-- 若已安装元忆（yotta-memory），重要事实用 `remember` 落盘，边界/偏好用私密类型；
+- **每次记录都写明「本次落到哪里」**：哪条 `.learnings/`、哪个状态文件、元忆哪条记忆——不写一句「已记录」就结束；
+- 若已安装元习（yotta-learn），用它的条目协议沉淀，格式统一可检索；若已安装元忆（yotta-memory），重要事实用 `remember` 落盘，边界/偏好用私密类型；
+- **未装元习 / 元忆时明说兜底**：本次用项目日志 + 交接锚点记录，并提示装后可升级；不无声降级，不让人误以为已进记忆库；
 - 涉及用户隐私或敏感信息时，先获得用户同意再记录；
 - 沉淀不是攒文本：每条要能回答「当时发生什么 / 为什么 / 下次怎么办」。
 

package/references/faq.md

@@ -5,6 +5,10 @@
 是的。复杂、不可逆、会动文件或外部通道的任务先出方案；一次性问答、复制粘贴、
 查一个词这类低风险小任务不需要走完整流程。
 
+分不清时套客观信号：写/删文件、步骤明显多于 3 步、有副作用（发布/推送/授权/动数据）、
+跨会话——命中任一至少走「方案」级。「改 3 行配置」看着小，但改的是现有配置，也要先给
+影响面与回滚；「改 typo、格式化、加注释」这类改动极小且可回滚的机械步骤才可以直接做。
+
 ## AI 没问就直接开始改，怎么办？
 
 让它停下来，说明已经做了什么和影响，再补一份方案，等确认后继续。这个情况本身应该
@@ -41,3 +45,26 @@
 不会。元伴常驻的是「判定规则」，不是「全套流程」。收到任务后先做 30 秒判定：
 复杂、长任务、有副作用或跨会话才走完整协议；一次性问答、查一个词、复制改写会直接回答。
 好的协作协议应该省时间，不是制造仪式。
+
+## 怎么 10 秒看出 AI 有没有按协议走？
+
+交付时扫四点：① 走协议前有没有一行「目标 + 验收」简报；② 动文件/发布前有没有先给方案；
+③ 说完成时有没有贴证据（命令输出/文件路径/日志）；④ 不确定的结论有没有标注
+「实测过 / 仅查到文档 / 无法核实」。任一点缺失，先要求补齐再验收。
+
+## 验收标准怎么写？
+
+写成可勾选清单，别写「做好」「完成」。对照：
+
+- ❌ 验收：把功能做完、没问题。
+- ✅ 验收：`python selftest.py` 全绿；边界 X / Y / Z 已覆盖；输出文件能在 `deliverables/` 打开预览；未改动清单外文件。
+
+## AI 说「已记录」，怎么确认真记了？
+
+要求它说清本次落到哪里：哪个状态文件、哪条经验条目、哪条记忆。没装元习（yotta-learn）/
+元忆（yotta-memory）时，它应明说用项目日志 + 交接锚点兜底——不无声降级，不让你以为已沉淀。
+
+## 元伴和更严的本地规则冲突怎么办？
+
+元伴是跨智能体协作协议的最低公共层，允许任何一侧用更严的本地铁律覆盖或加严；冲突时
+以更严者为准。已有严格纪律的团队不会觉得元伴多余，没有严格纪律的也不会觉得它可欺。