jiangwill2023

# memory-backfill Skill

**版本：** v1.0  
**创建日期：** 2026-04-26  
**来源：** Agent 记忆补强两层方法论验证  

---

## 用途

标准化执行 Agent 记忆补强任务，将"框架型记忆"升级为"项目型记忆"，再升级为"结果闭环型记忆"。

---

## 适用场景

- Agent 的 MEMORY.md 停留在抽象原则层，缺少真实项目事实
- 团队需要统一记忆沉淀口径
- 新 Agent 接入后需要快速建立项目级记忆
- 定期复盘时需要升级旧记忆

---

## 两层架构

### 第一层：项目块型记忆

**目标：** 不再只写抽象原则，而是补真实项目事实。

**每条记忆必须包含：**
1. 项目名
2. 我负责什么
3. 关键决策
4. 关键坑点
5. 可复用经验

**完成标准：**
- 至少补 3 个项目块
- 写入 `MEMORY.md`
- 写入当天 `memory/YYYY-MM-DD.md`

---

### 第二层：结果闭环型 + 证据锚点型记忆

**目标：** 不再只回答"做过什么"，而是回答"最后成了没有、证据在哪、还卡在哪"。

**每条记忆必须包含：**
1. 最终状态（DONE / PARTIAL / BLOCKED）
2. 是否彻底解决
3. 已完成/已落地阶段（用 ✅ 标记）
4. 仍停在观察/未落地阶段（用 ⏸️ 标记）
5. 证据路径（文件路径 / 线上验证 / 日志锚点）
6. 最终交付证据
7. 遗留缺口
8. 默认回答口径

**完成标准：**
- 每个重点项目都升级为上述结构
- 写入 `MEMORY.md`
- 写入当天 `memory/YYYY-MM-DD.md`

---

## 执行流程

### Step 1：诊断当前记忆状态
```
1. 读取 AGENTS.md / SOUL.md / USER.md / MEMORY.md
2. 读取最近 7 天 memory/*.md
3. 判断当前记忆层级：
   - 只有框架/原则 → 需要第一层
   - 有项目块但无结果闭环 → 需要第二层
   - 已有结果闭环 → 只需维护
```

### Step 2：下发记忆补强任务
```
task_id: memory-backfill-layer[N]-[agent]-[date]

任务目标：[第一层/第二层] 记忆补强

重点补：
1. [项目 1 - 脱敏后用真实项目名替换]
2. [项目 2 - 脱敏后用真实项目名替换]
3. [项目 3 - 脱敏后用真实项目名替换]

要求：
- 更新 MEMORY.md 与当天 memory 日志
- 必须写：[对应层级要求的字段]
- 回执格式：
  - status
  - claimed deliverable
  - evidence path
  - attached_to_mainline
  - single biggest gap
  - upgraded_to
```

### Step 3：验收与核验
```
1. 优先直接查文件产物：
   - workspace-[agent]/MEMORY.md
   - workspace-[agent]/memory/[date].md
2. 不依赖消息回执判断完成
3. 对照模板检查字段完整性
```

### Step 4：固化与归档
```
1. 将本次补强记录写入当天 memory 日志
2. 如有跨 agent 可复用经验，沉淀到方法论文档
3. 标记哪些项目仍为 PARTIAL / BLOCKED，纳入后续跟进队列
```

---

## 验收标准

### 第一层验收清单
- [ ] 至少 3 个项目块
- [ ] 每块包含：项目名 / 负责内容 / 关键决策 / 关键坑点 / 可复用经验
- [ ] 已写入 MEMORY.md
- [ ] 已写入当天 memory 日志

### 第二层验收清单
- [ ] 每个项目有最终状态（DONE/PARTIAL/BLOCKED）
- [ ] 每个项目有证据路径
- [ ] 每个项目有默认回答口径
- [ ] 每个项目有遗留缺口说明
- [ ] 已写入 MEMORY.md
- [ ] 已写入当天 memory 日志

---

## 常见陷阱

### 陷阱 1：只补框架不补事实
**表现：** 写了很多"应该怎么做"，但没有"我做了什么项目"

**解法：** 强制要求每条记忆必须带项目名

### 陷阱 2：只报 DONE 不报 PARTIAL/BLOCKED
**表现：** 所有项目都报完成，但实际缺少验证证据

**解法：** 明确定义 DONE/PARTIAL/BLOCKED 口径，要求必须有证据支撑

### 陷阱 3：消息回执 timeout 就判失败
**表现：** 因为 timeout 就认为 agent 没做

**解法：** 优先查文件产物，不等回执

### 陷阱 4：证据锚点模糊
**表现：** "我记得做了"、"应该是完成了"

**解法：** 强制要求具体文件路径 / 线上验证 URL / 日志锚点

---

## 可复用模板

### 第一层模板
```markdown
### 项目 X：[项目名]
- **我负责什么**：
- **关键决策**：
- **关键坑点**：
- **可复用经验**：
```

### 第二层模板
```markdown
### 项目 X：[项目名]
- **最终状态**：DONE / PARTIAL / BLOCKED
- **是否彻底解决**：是/否
- **已完成/已落地阶段**：
  - ✅ ...
- **仍停在观察/未落地阶段**：
  - ⏸️ ...
- **证据路径**：
  - ...
- **最终交付证据**：
  - ...
- **遗留缺口**：
  - ...
- **默认回答口径**："..."
```

---

## 相关 Skill

- `result-closure-memory` - 结果闭环型记忆写入规范
- `evidence-anchor` - 证据锚点定义与验收
- `taskflow` - 任务流管理

---

## 维护者

- 创建者：小强（qiang）
- 创建日期：2026-04-26
- 来源项目：Agent 记忆补强两层方法论验证

---

## 变更日志

| 版本 | 日期 | 变更内容 |
|------|------|----------|
| v1.0 | 2026-04-26 | 初始版本，基于 4 位 agent 验证通过 |

FILE:_meta.json
{
  "ownerId": "kn79dqtv1kxj06f28ce114rma582bebj",
  "slug": "memory-backfill",
  "version": "1.0.0",
  "publishedAt": 1777188333271
}

---
name: kimi2.5skill
description: Troubleshoot and operate Kimi 2.5 / OpenClaw image understanding. Use when image recognition fails, OCR/images cannot be analyzed, `image` tool reports `Unknown model`, configured vision models are ignored at runtime, or you need a safe recovery workflow for OpenClaw image-capable models.
---

# kimi2.5skill

处理 OpenClaw 中 Kimi 2.5 / 识图模型的排障、恢复、验证与运维收口。

## 快速流程
1. 先做 runtime 实测，不要只看配置文件
2. 再检查：
   - `~/.openclaw/openclaw.json`
   - `~/.openclaw/agents/<agent>/agent/models.json`
3. 如果出现 `Unknown model`，优先怀疑 agent 级 `models.json` 的非法 provider 配置导致整份自定义模型注册表加载失败
4. 修复后必须重启 gateway，并跑一张真实图片回归测试

## 参考文件
- 修复流程：`references/recovery-playbook.md`
- 本次事件：`references/incident-2026-04-14.md`

## 本轮已验证结论（2026-04-14）
本轮问题的真实根因是：

> agent 级 `models.json` 中的自定义 `codex` provider 配置不合法，导致模型注册表加载异常，继而让 `image` runtime 报 `Unknown model`。

已验证修复点：
- `/Users/admin-ai/.openclaw/agents/qiang/agent/models.json`
- `/Users/admin-ai/.openclaw/agents/sally-bot/agent/models.json`

移除有问题的 `codex` provider 后，`image` 工具已成功返回图片描述，说明识图 runtime 恢复。

## 成功标准
以下同时满足才算修好：
- 不再出现 `Unknown model`
- `image` 工具返回正常图片描述 / OCR 结果
- gateway 状态正常
- 至少完成一张真实图片回归测试

## 收口口径
恢复后统一表述：
- 识图已恢复可用
- 根因是 agent 级 `models.json` 非法 provider 配置污染了 image runtime 注册表
- 后续若再遇 `Unknown model`，优先检查 `~/.openclaw/agents/<agent>/agent/models.json`

FILE:references/incident-2026-04-14.md
# Incident 2026-04-14

## Summary
OpenClaw image understanding failed even though image-capable models were present in config.

## Root cause
Agent-level `models.json` included an invalid custom provider block (`codex`) that broke custom model registry loading for image runtime.

## Observed effect
- `image` tool returned `Unknown model`
- static config appeared valid
- runtime behavior contradicted config expectations

## Fix applied
Removed invalid `codex` provider from affected agent-level `models.json` files:
- `/Users/admin-ai/.openclaw/agents/qiang/agent/models.json`
- `/Users/admin-ai/.openclaw/agents/sally-bot/agent/models.json`

## Validation
After repair:
- gateway was healthy
- `image` tool returned a normal image description
- notifications were sent to relevant agents

## Durable lesson
Config presence is not runtime proof. Trust runtime verification over static JSON presence.

FILE:references/recovery-playbook.md
# Recovery Playbook

## Scope
Use this playbook when OpenClaw image understanding fails with symptoms like:
- `Unknown model`
- configured vision model exists in JSON but runtime does not recognize it
- image/OCR suddenly stops working across one or more agents

## Confirm the symptom first
Do runtime verification first:
1. Run `openclaw status`
2. Run an actual `image` tool call against a real local or inbound image
3. Treat runtime output as ground truth

Do not call it fixed if you only checked config files.

## Files to inspect
- `~/.openclaw/openclaw.json`
- `~/.openclaw/agents/<agent>/agent/models.json`

## Highest-probability root cause
A single invalid provider block inside agent-level `models.json` can cause the custom model registry to fail loading.

In the 2026-04-14 incident, the invalid block was a custom `codex` provider definition. Removing it restored image runtime registration.

## Minimal repair sequence
1. Back up the affected `models.json`
2. Remove only the invalid provider block
3. Restart gateway
4. Run a real image regression test
5. Notify affected agents

## Success criteria
All of these must be true:
- no `Unknown model`
- image tool returns a valid description or OCR result
- gateway healthy
- at least one real image regression passed

## Non-success criteria
These do not count as fixed:
- model exists in config
- service is running
- no real image tested

---
name: hospitable-ops
description: Operate, debug, and automate Hospitable via Public API with a safe read-first workflow and non-price calendar controls. Use when working with Hospitable properties, reservations, calendar reads, write verification, blocking/unblocking dates, check-in/check-out restrictions, property mapping, or cross-channel automation logic around Airbnb/Booking/Hospitable. Especially use for: (1) verifying Hospitable API auth and endpoints, (2) exporting properties/reservations/calendar, (3) testing or applying non-price calendar writes, (4) building Hospitable-based automation/reporting, (5) debugging delayed sync or write semantics.
---

# Hospitable Ops

Use Hospitable as the unified operational base. Prefer read-first, then safe write verification, then controlled non-price writes.

## Core rules
- Treat Hospitable as the system of operational judgment, especially for unified property UUIDs, calendar state, reservations, and parent/child exclusion logic.
- Never expose tokens in chat, logs, screenshots, or shared files.
- Use Hospitable Public API v2 as the only active execution path for reads and automation in this workspace.
- MCP has been removed from the current Hospitable operating path; do not route or describe Hospitable work through MCP.
- Use persistent config or local scripts; avoid session-only ad hoc setup when building repeatable workflows.
- Default to non-price actions only. Price, currency, and money-related changes must be discussed first and then changed manually by the human.
- Assume write effects may be asynchronous. Do not judge failure from an immediate readback alone.
- In this workspace, do not rely on OpenClaw runtime inheriting shell env automatically; prefer script-level loading from `/Users/admin-ai/.openclaw/workspace-qiang/.env.local` for repeatable Hospitable execution.
- `HOSPITABLE_TOKEN` must contain the token body only; never include a leading `Bearer ` prefix in the env value.

## Standard workflow
1. Verify `HOSPITABLE_TOKEN` is available in the current execution environment without printing it.
2. If runtime inheritance is uncertain, use local script loading from `.env.local` instead of re-debugging shell/profile inheritance.
3. Read data first:
   - properties
   - reservations
   - calendar
4. Save JSON with `statusCode` and `body` envelope.
5. Build operational judgments from Hospitable first; layer Booking/Airbnb exceptions after.
6. For writes, probe safely:
   - identify method
   - identify minimal body
   - test on low-risk future date
   - re-read after delay
7. Only after semantics are clear, apply controlled non-price changes.

## Known API behavior
### Read
Use bearer auth plus `Accept: application/json`.

Current workspace rule:
- default to the current validated token
- treat older/previous Hospitable tokens as deprecated unless the human explicitly restores one
- prefer local env file loading over shell-history fallback or session-only manual export

Common read paths:
- `properties`
- `reservations?properties[]=<uuid>`
- `properties/<uuid>/calendar?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD`

### Runtime inheritance readback (validated)
Validated facts in this workspace:
- host-side token is valid and can return `statusCode: 200` on `properties`
- OpenClaw agent runtime did not automatically inherit `HOSPITABLE_TOKEN`
- repeatable workaround: load `/Users/admin-ai/.openclaw/workspace-qiang/.env.local` directly inside Hospitable scripts
- after enabling script-level env loading, `node scripts/hospitable-read.js properties --per-page 1` returned `statusCode: 200`

### Current script CLI contract
`/Users/admin-ai/.openclaw/workspace-qiang/scripts/hospitable-read.js`

Supported commands:
- `properties [--per-page N]`
- `reservations --property <uuid> [--per-page N]`
- `calendar --property <uuid> --start YYYY-MM-DD --end YYYY-MM-DD`

Important:
- `calendar` uses `--start` and `--end`
- do not use `--start-date` / `--end-date` with this script
- keep `#!/usr/bin/env node` on line 1 if editing the script header

### Write
For calendar writes:
- route: `properties/<uuid>/calendar`
- supported method: `PUT`
- `PATCH` is not supported
- request body must include `dates`
- minimal accepted structure:
```json
{
  "dates": [
    { "date": "YYYY-MM-DD" }
  ]
}
```

### Verified non-price semantics
#### Block a whole date
```json
{
  "dates": [
    { "date": "YYYY-MM-DD", "available": false }
  ]
}
```
Expected eventual readback:
- `status.reason = BLOCKED`
- `status.source = api`
- `status.source_type = VENDOR`
- `status.available = false`

#### Restrict check-in / check-out
```json
{
  "dates": [
    {
      "date": "YYYY-MM-DD",
      "closed_for_checkin": true,
      "closed_for_checkout": true
    }
  ]
}
```
Expected eventual readback:
- `closed_for_checkin = true`
- `closed_for_checkout = true`
- day may still remain `AVAILABLE`

## Operational boundaries
### Allowed direct actions
- non-price calendar block/unblock
- check-in/check-out restrictions
- non-price operational lock windows
- parent/child exclusion enforcement
- cross-channel conflict prevention using non-price controls
- one-time cleanup of legacy order occupancy when the business rule is already confirmed

### Human-only actions
- price
- currency
- money-related changes
- pricing strategy decisions

## Long-term operating model
Reduce the property system into three stable forms whenever possible:
1. Airbnb-only
2. dual-channel managed by Hospitable native mechanisms
3. main-house gate open/closed

Treat legacy exceptions as temporary cleanup layers, not permanent structure.

### Current NXM cleanup model
- `mute(booking)` is a historical order source only and should not take new sales.
- `206 -> 201` is a temporary operational occupancy transfer caused by legacy mute orders.
- customer-visible order display can remain original while operational occupancy moves internally for anti-overbooking control.
- after cleanup, return to the three stable forms above.

## Recommended local files
- `scripts/hospitable-read.js`
- `scripts/hospitable-write-probe.js`
- exported JSON snapshots with `statusCode/body`
- rule config files for object tiers and lock windows

## Delay-aware verification
After a write returns `202 accepted`:
1. wait before declaring failure
2. re-read the same date window
3. compare operational fields, not only high-level availability
4. check whether the change is semantic (blocked vs closed_for_checkin/checkout)

## Good output pattern
Report in this order:
1. current status
2. exact object/date tested
3. request accepted or rejected
4. delayed readback result
5. operational conclusion
6. single biggest remaining gap

FILE:scripts/hospitable-read.js
#!/usr/bin/env node
const https = require('https');

const token = process.env.HOSPITABLE_TOKEN;
const base = process.env.HOSPITABLE_BASE_URL || 'https://public.api.hospitable.com/v2/';

function usage() {
  console.error(`Usage:
  hospitable-read.js properties [--per-page N]
  hospitable-read.js reservations --property <uuid> [--per-page N]
  hospitable-read.js calendar --property <uuid> --start YYYY-MM-DD --end YYYY-MM-DD
`);
  process.exit(2);
}
if (!token) {
  console.error(JSON.stringify({ error: 'HOSPITABLE_TOKEN is required' }, null, 2));
  process.exit(2);
}
const args = process.argv.slice(2);
if (!args.length) usage();
function getArg(flag, required = false) {
  const i = args.indexOf(flag);
  if (i === -1) return required ? usage() : null;
  const v = args[i + 1];
  if (!v || v.startsWith('--')) usage();
  return v;
}
function requestJson(path) {
  return new Promise((resolve, reject) => {
    const url = new URL(path, base);
    const req = https.request(url, { method: 'GET', headers: { Authorization: `Bearer token`, Accept: 'application/json' } }, (res) => {
      let body = '';
      res.on('data', c => body += c);
      res.on('end', () => {
        let parsed = null;
        try { parsed = JSON.parse(body); } catch (_) {}
        resolve({ statusCode: res.statusCode, headers: res.headers, body: parsed ?? body });
      });
    });
    req.on('error', reject);
    req.end();
  });
}
(async () => {
  const cmd = args[0];
  const perPage = getArg('--per-page') || '5';
  let result;
  if (cmd === 'properties') {
    result = await requestJson(`properties?per_page=encodeURIComponent(perPage)`);
  } else if (cmd === 'reservations') {
    const property = getArg('--property', true);
    result = await requestJson(`reservations?properties[]=encodeURIComponent(property)&per_page=encodeURIComponent(perPage)`);
  } else if (cmd === 'calendar') {
    const property = getArg('--property', true);
    const start = getArg('--start', true);
    const end = getArg('--end', true);
    result = await requestJson(`properties/encodeURIComponent(property)/calendar?start_date=encodeURIComponent(start)&end_date=encodeURIComponent(end)`);
  } else usage();
  console.log(JSON.stringify(result, null, 2));
})();

FILE:scripts/hospitable-write-probe.js
#!/usr/bin/env node
const https = require('https');
const token = process.env.HOSPITABLE_TOKEN;
const base = process.env.HOSPITABLE_BASE_URL || 'https://public.api.hospitable.com/v2/';
if (!token) {
  console.error(JSON.stringify({ error: 'HOSPITABLE_TOKEN is required' }, null, 2));
  process.exit(2);
}
const args = process.argv.slice(2);
const method = args[0] || 'OPTIONS';
const pathArg = args[1] || 'properties';
const body = args[2] || null;
function request(pathname, method, body) {
  return new Promise((resolve, reject) => {
    const url = new URL(pathname, base);
    const req = https.request(url, {
      method,
      headers: {
        Authorization: `Bearer token`,
        Accept: 'application/json',
        ...(body ? { 'Content-Type': 'application/json' } : {})
      }
    }, (res) => {
      let raw = '';
      res.on('data', c => raw += c);
      res.on('end', () => {
        let parsed = null;
        try { parsed = JSON.parse(raw); } catch (_) {}
        resolve({ method, url: url.toString(), statusCode: res.statusCode, headers: res.headers, body: parsed ?? raw });
      });
    });
    req.on('error', reject);
    if (body) req.write(body);
    req.end();
  });
}
request(pathArg, method, body).then(r => console.log(JSON.stringify(r, null, 2))).catch(err => {
  console.error(JSON.stringify({ error: String(err) }, null, 2));
  process.exit(1);
});

# evidence-anchor Skill

**版本：** v1.0  
**创建日期：** 2026-04-26  
**来源：** Agent 记忆补强两层方法论验证  

---

## 用途

标准化定义和验收"证据锚点"，确保长期记忆不是"口头记忆"，而是可验证、可回溯、可复用的资产。

---

## 适用场景

- 项目记忆需要沉淀证据
- 结果闭环型记忆写入
- 跨 agent 交接时需要统一证据口径
- 定期复盘时需要验证历史结论

---

## 证据分级

### Level 1：直接证据（最强）

**定义：** 可直接验证项目状态/结果的原始证据。

**示例：**
| 类型 | 示例 |
|------|------|
| 线上验证 | `https://example.com/` 返回 200 OK |
| 文件路径 | `/opt/xxx/app/current/index.html` |
| 配置路径 | `/etc/nginx/conf.d/xxx.conf` |
| Commit hash | `abc123def` |
| CI 日志 | `GitHub Actions Run #456` |
| 部署时间戳 | `YYYY-MM-DD HH:MM TZ` |
| 签署文件 | `projects/xxx-contract-signed.pdf` |
| 银行流水 | `bank-statement-YYYY-MM.pdf` |

**验收标准：**
- 路径/URL 可直接访问或查验
- 时间戳精确到日（最好到时分）
- 文件真实存在且内容匹配

---

### Level 2：间接证据（中等）

**定义：** 可佐证项目进展，但不能直接证明结果的证据。

**示例：**
| 类型 | 示例 |
|------|------|
| 设计文档 | `projects/xxx-design.md` |
| 会议纪要 | `meetings/2026-04-16-xxx.md` |
| 方案草稿 | `projects/xxx-plan-v0.md` |
| 工作卡 | `xxx-work-card.md` |
| 基线文件 | `xxx.baseline.js` |

**验收标准：**
- 文档真实存在
- 内容与所述项目相关
- 有明确创建/修改日期

**使用限制：**
- 不能单独支撑 DONE 状态
- 可支撑 PARTIAL 状态（设计已完成，实施未启动）

---

### Level 3：引用证据（最弱）

**定义：** 对他人陈述/记忆的引用，不能独立验证。

**示例：**
| 类型 | 示例 |
|------|------|
| 记忆引用 | `memory/2026-04-16.md` 中的记录 |
| 口头确认 | "用户说已经完成了" |
| 二手转述 | "听某某说部署好了" |

**验收标准：**
- 引用路径明确
- 原始来源可追溯

**使用限制：**
- 不能单独作为项目状态证据
- 仅可作为辅助佐证
- 优先追 Level 1/2 证据

---

## 证据锚点定义规范

### 标准格式

每条证据锚点应包含：

```markdown
- **证据类型**：[线上验证/文件路径/配置路径/日志记录/签署文件/其他]
- **证据路径**：[具体路径或 URL]
- **验证方式**：[如何查验该证据]
- **证据结论**：[该证据支撑什么结论]
```

### 示例

#### 示例 1：官网修复证据（脱敏版）
```markdown
- **证据类型**：线上验证 + 文件路径
- **证据路径**：
  - `https://example.com/` 返回 200 OK
  - `/opt/xxx/app/current/index.html`
  - `/etc/nginx/conf.d/xxx.conf`
- **验证方式**：
  - curl 线上 URL
  - SSH 登录服务器查看文件
  - readback Nginx 配置
- **证据结论**：官网主链路已恢复，Nginx 配置已修复
```

#### 示例 2：部署项目证据（脱敏版）
```markdown
- **证据类型**：文件路径 + 健康检查
- **证据路径**：
  - `/opt/xxx/docker-compose.yml`
  - `/health` 端点返回 200
- **验证方式**：
  - SSH 查看部署文件
  - curl https://example.com/health
- **证据结论**：部署骨架已落地，健康检查可用
```

#### 示例 3：融资项目证据（脱敏版）
```markdown
- **证据类型**：文档路径 + 许可记录
- **证据路径**：
  - `projects/xxx-finance.md`
  - 许可记录（YYYY-MM-DD 取得）
- **验证方式**：
  - 读取项目文档
  - 查验许可编号/官方记录
- **证据结论**：融资方案已形成，许可已落地，银行贷款未见落地证据
```

---

## 证据验收流程

### Step 1：识别证据类型
```
判断证据属于：
- Level 1（直接证据）
- Level 2（间接证据）
- Level 3（引用证据）
```

### Step 2：验证证据有效性
```
检查：
- 路径/URL 是否真实存在
- 内容是否与所述匹配
- 日期是否在合理范围内
- 是否有篡改/过期风险
```

### Step 3：判断证据支撑力
```
对照状态判断：
- DONE：需要 Level 1 证据支撑关键阶段
- PARTIAL：Level 1 + Level 2 混合
- BLOCKED：只有 Level 2/3 或无证据
```

### Step 4：写入记忆
```
按标准格式写入：
- 证据类型
- 证据路径
- 验证方式
- 证据结论
```

### Step 5：定期复核
```
建议每 1-3 个月复核：
- 线上 URL 是否仍可达
- 文件是否仍存在于路径
- 配置是否仍生效
- 是否有新证据可补充
```

---

## 证据与状态映射

| 项目状态 | 必需证据 | 可选证据 |
|----------|----------|----------|
| **DONE** | Level 1 证据支撑所有关键阶段 | Level 2 辅助说明设计/背景 |
| **PARTIAL** | Level 1 证据支撑已落地阶段 + Level 2 说明未落地阶段 | Level 3 引用记忆 |
| **BLOCKED** | Level 2 证明任务已接收 + Level 3 说明阻塞原因 | - |

---

## 常见陷阱

### 陷阱 1：只有文档没有实施证据
**表现：** 只有 `xxx-plan.md`，没有部署/签署/上线证据

**解法：** 明确标注"设计已完成，实施未启动"，状态最多报 PARTIAL

### 陷阱 2：证据路径模糊
**表现：** "服务器上有"、"应该部署了"

**解法：** 强制要求具体路径，如 `/opt/xxx/app/current`

### 陷阱 3：用 Level 3 撑 DONE
**表现：** 只有"听某某说完成了"，没有 Level 1 证据

**解法：** 降级为 PARTIAL/BLOCKED，直到拿到 Level 1 证据

### 陷阱 4：证据过期未更新
**表现：** URL 已 404、文件已删除、配置已覆盖

**解法：** 定期复核，证据失效时同步更新记忆状态

---

## 证据锚点模板

### 模板 1：线上服务证据
```markdown
- **证据类型**：线上验证
- **证据路径**：`https://[domain]/[path]`
- **验证方式**：curl / browser 访问
- **预期结果**：返回 [状态码] / 显示 [内容]
- **证据结论**：[支撑什么结论]
```

### 模板 2：服务器文件证据
```markdown
- **证据类型**：文件路径
- **证据路径**：`/path/to/file`
- **验证方式**：SSH 登录 + cat/ls
- **预期结果**：文件存在，内容包含 [关键信息]
- **证据结论**：[支撑什么结论]
```

### 模板 3：配置证据
```markdown
- **证据类型**：配置路径
- **证据路径**：`/path/to/config.conf`
- **验证方式**：readback 配置文件
- **预期结果**：配置包含 [关键规则]
- **证据结论**：[支撑什么结论]
```

### 模板 4：日志证据
```markdown
- **证据类型**：日志记录
- **证据路径**：`memory/YYYY-MM-DD.md` 或 `logs/xxx.log`
- **验证方式**：读取日志文件
- **预期结果**：日志包含 [关键事件/时间戳]
- **证据结论**：[支撑什么结论]
```

---

## 相关 Skill

- `memory-backfill` - 记忆补强标准化流程
- `result-closure-memory` - 结果闭环型记忆写入规范
- `taskflow` - 任务流管理

---

## 维护者

- 创建者：小强（qiang）
- 创建日期：2026-04-26
- 来源项目：Agent 记忆补强两层方法论验证

---

## 变更日志

| 版本 | 日期 | 变更内容 |
|------|------|----------|
| v1.0 | 2026-04-26 | 初始版本，基于 4 位 agent 验证通过 |

FILE:_meta.json
{
  "ownerId": "kn79dqtv1kxj06f28ce114rma582bebj",
  "slug": "evidence-anchor",
  "version": "1.0.0",
  "publishedAt": 1777188316238
}

---
name: canva-skill
description: Create, export, upload assets to, and manage Canva designs via the Canva Connect API. Use when the user wants to create social posts, posters, PPT/slide visuals, export Canva designs as PNG/JPG/PDF, list recent Canva designs, upload local images to Canva, or autofill brand templates with content.
---

# Canva Skill

Use Canva Connect API for design creation, export, and asset upload workflows.

## Prerequisites

Create a Canva Integration:
1. Go to https://www.canva.com/developers/
2. Create a new integration
3. Get your Client ID and Client Secret

Set environment variables:

```bash
export CANVA_CLIENT_ID="your_client_id"
export CANVA_CLIENT_SECRET="your_client_secret"
```

Authenticate on first use and store tokens in `~/.canva/tokens.json`.

## API Base URL

```bash
https://api.canva.com/rest/v1
```

## Authentication

Get access token from local token file:

```bash
ACCESS_TOKEN=$(cat ~/.canva/tokens.json | jq -r '.access_token')
```

Refresh tokens automatically when the auth flow supports it.

## Core Operations

### List Designs

```bash
curl -s "https://api.canva.com/rest/v1/designs" \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq .
```

### Get Design Details

```bash
curl -s "https://api.canva.com/rest/v1/designs/{designId}" \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq .
```

### Create Design from Template

```bash
curl -X POST "https://api.canva.com/rest/v1/autofills" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_template_id": "TEMPLATE_ID",
    "data": {
      "title": {"type": "text", "text": "Your Title"},
      "body": {"type": "text", "text": "Your body text"}
    }
  }'
```

### Export Design

Start export job:

```bash
curl -X POST "https://api.canva.com/rest/v1/exports" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "design_id": "DESIGN_ID",
    "format": {"type": "png", "width": 1080, "height": 1080}
  }'
```

Check export status:

```bash
curl -s "https://api.canva.com/rest/v1/exports/{jobId}" \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq .
```

### Upload Asset

```bash
curl -X POST "https://api.canva.com/rest/v1/asset-uploads" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  -H 'Asset-Upload-Metadata: {"name": "my-image.png"}' \
  --data-binary @image.png
```

### List Brand Templates

```bash
curl -s "https://api.canva.com/rest/v1/brand-templates" \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq .
```

## Export Formats

- PNG: width, height, lossless
- JPG: width, height, quality (1-100)
- PDF: standard, print
- MP4: for video designs
- GIF: for animated designs

## Common Workflows

### Create Instagram Post
1. List brand templates
2. Find an Instagram post template
3. Autofill with content
4. Export as PNG 1080x1080
5. Download exported file

### Create Carousel
1. Create multiple designs using autofill
2. Export each as PNG
3. Combine for posting

### Batch Export
1. List designs
2. Loop through and export each
3. Download all files

## Error Handling

Handle common errors clearly:
- 401: Token expired, refresh needed
- 403: Missing required scope
- 404: Design/template not found
- 429: Rate limit exceeded

## Required Scopes

- `design:content:read`
- `design:content:write`
- `asset:read`
- `asset:write`
- `brandtemplate:content:read`

## Tips

- Prefer Brand Templates for posters and slides when available.
- Batch exports to reduce repetitive work.
- Cache commonly used template IDs locally.
- Poll export jobs until complete before downloading.

## Current Status

This local skill skeleton is installed in the workspace, but Canva API use is not ready until the integration credentials and first-time OAuth authentication are completed.