diff --git a/CHANGELOG.md b/CHANGELOG.md index ad644db5..8ac486dd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- `evaluation/`:评测整套 Edges(用例、harness、报告)。系统元工作,不是知识生命周期阶段。 +- `observation/`:观测运行与使用(脱敏 run log、指标与仪表盘笔记)。不替代 `.memory` 决策。 - `docs/adr/`:记录领域决策;首条为对话整理采用复盘四栏。 - CONTEXT 增加「复盘四栏」及四栏术语。 - CONTEXT 增加 Task、`edges-tasks-status`、Task Run Log、backlog(Task)。 diff --git a/README.md b/README.md index 3a8c596c..5174b349 100644 --- a/README.md +++ b/README.md @@ -107,6 +107,10 @@ knowledge/projects/foo/report.md → knowledge/archive/projects/foo/report.md | [`shared-extensions/`](shared-extensions/README.md) | 跨机器、跨 Agent 共用的个人 harness | 离开 Edges 仍然有价值 | | [`bin/`](bin/README.md) | 安装后由人反复调用的命令 | 加入 `$PATH` | | [`scripts/`](scripts/README.md) | 初始化、构建、迁移等维护脚本 | 通过 `pnpm` 调用,不加入 `$PATH` | +| [`evaluation/`](evaluation/README.md) | 评测整套 Edges | 系统元工作,不是知识生命周期阶段 | +| [`observation/`](observation/README.md) | 观测运行与使用 | 运营观测,不替代 `.memory` 决策 | + +`evaluation/` 与 `observation/` 是系统实现旁的支撑目录:前者对照假设,后者记录野外现象。它们不进入 notes → edges → archive 主链;观测或评测若产生新洞察,仍须回到捕获入口。 捕获入口最终回到同一套知识模型:人可以使用 `bin/new-note`;有 shell 的 Agent 使用 [`edges-note` CLI](extensions/clis/README.md),获得稳定参数和 JSON 输出;没有 shell 的宿主使用 [`new-note` MCP](extensions/mcp-servers/new-note/README.md)。它们复用同一条 Note 入库链路。 @@ -158,7 +162,7 @@ pnpm test - 仓库级变更记录在 [`CHANGELOG.md`](CHANGELOG.md),tag 使用 `vX.Y.Z`。 - 对外 skill 各自独立 semver;`shared-extensions/` 整层使用自己的 [`VERSION`](shared-extensions/VERSION) 与 [`CHANGELOG.md`](shared-extensions/CHANGELOG.md)。 -进一步文档:[Edges 扩展](extensions/README.md) · [共享 Agent harness](shared-extensions/README.md) · [用户命令](bin/README.md) · [维护脚本](scripts/README.md) +进一步文档:[Edges 扩展](extensions/README.md) · [共享 Agent harness](shared-extensions/README.md) · [用户命令](bin/README.md) · [维护脚本](scripts/README.md) · [评测](evaluation/README.md) · [观测](observation/README.md) ## 公开仓库边界 diff --git a/evaluation/README.md b/evaluation/README.md new file mode 100644 index 00000000..6371c0b2 --- /dev/null +++ b/evaluation/README.md @@ -0,0 +1,36 @@ +# 评测 (evaluation/) + +`evaluation/` 评测**整套 Edges**:skills、记忆循环、note→edge 流程、Agent 对着本仓库的行为等。这是系统元工作,不是个人知识笔记,也不进入 notes → edges → archive 主链。 + +## 放什么 + +- 评测用例、harness、benchmark 定义、scorecard +- 对照某次变更或某条假设的评测报告 +- 用来判断「系统有没有变好」的可复现实验设计 + +## 不放什么 + +- 个人认知资产、研究笔记、对外博客 → [`knowledge/`](../knowledge/) +- 已采纳的决策、纠错、操作手册 → [`.memory/`](../.memory/) +- 接入 Edges 的 CLI / MCP / skill 实现 → [`extensions/`](../extensions/README.md) +- 野外使用记录、运行日志、仪表盘笔记 → [`observation/`](../observation/README.md) +- 编造的数据集、假分数、尚未跑过的「结果」 + +本仓公开。用例与报告按根 README「公开仓库边界」脱敏;不要写入凭据、未公开 IP 或可识别个人。 + +## 和其他目录的关系 + +| 目录 | 关系 | +| --- | --- | +| [`knowledge/`](../knowledge/) | 认知资产。评测可以*调用*其中的材料当输入,但不把报告写成 Note / Edge / Post。一条评测结论若值得沉淀为可复用判断,先回到捕获入口。 | +| [`.memory/`](../.memory/) | 运营账本。评测*发现*并被采纳的决策写进 `.memory`;过程、用例和分数留在本目录。 | +| [`extensions/`](../extensions/README.md) | 接口层。评测对象常常是 extensions 的行为;评测用例本身不因此变成 extension。 | +| [`observation/`](../observation/README.md) | 观测提供「野外看到了什么」;本目录把假设做成可复现对照。观测不是评测。 | + +## 起步布局 + +先有真实用例再往下加目录,不要预埋空数据文件。 + +- [`cases/`](cases/README.md):用例与 benchmark 定义 +- [`reports/`](reports/README.md):某次运行的报告 +- 本 README diff --git a/evaluation/cases/README.md b/evaluation/cases/README.md new file mode 100644 index 00000000..c113bc81 --- /dev/null +++ b/evaluation/cases/README.md @@ -0,0 +1,5 @@ +# cases/ + +评测用例与 benchmark 定义。有真实用例再往这里加文件;不要预埋空数据或虚构数据集。 + +约定见上一级 [README](../README.md)。 diff --git a/evaluation/reports/README.md b/evaluation/reports/README.md new file mode 100644 index 00000000..ab2b1697 --- /dev/null +++ b/evaluation/reports/README.md @@ -0,0 +1,5 @@ +# reports/ + +某次评测运行的报告。有真实结果再往这里写;不要预埋假分数。 + +约定见上一级 [README](../README.md)。 diff --git a/observation/README.md b/observation/README.md new file mode 100644 index 00000000..123765ec --- /dev/null +++ b/observation/README.md @@ -0,0 +1,37 @@ +# 观测 (observation/) + +`observation/` 观测 Edges **怎么被用**:telemetry 笔记、仪表盘备忘、run log、「野外看到了什么」。这是系统元工作,运营向观测,不替代 [`.memory/`](../.memory/) 里的决策,也不进入 notes → edges → archive 主链。 + +## 放什么 + +- 脱敏后的运行记录、使用轨迹摘要 +- 指标定义、仪表盘笔记、异常现象 +- 还没上升为决策的「我们看到了什么」 + +## 不放什么 + +- 凭据、未公开 IP、可识别个人、未脱敏的内部信息 +- 已确认的决策、纠错、必须遵守的做法 → [`.memory/`](../.memory/) +- 认知资产、研究笔记 → [`knowledge/`](../knowledge/) +- 接入 Edges 的接口实现 → [`extensions/`](../extensions/README.md) +- 可复现的评测用例、harness 与分数 → [`evaluation/`](../evaluation/README.md) +- 原始 `*.log` 文件(根 [`.gitignore`](../.gitignore) 会忽略它们);写成脱敏 markdown + +本仓公开。写入即等同公开发表,按根 README「公开仓库边界」判断。 + +## 和其他目录的关系 + +| 目录 | 关系 | +| --- | --- | +| [`knowledge/`](../knowledge/) | 认知资产。观测记录的是系统如何被使用,不是研究笔记。野外现象若值得沉淀为可复用判断,先回到捕获入口。 | +| [`.memory/`](../.memory/) | 运营账本。观测提供证据;被采纳的决策、纠错与约束写进 `.memory`,不把本目录当成第二份决策库。 | +| [`extensions/`](../extensions/README.md) | 接口层。观测可以记录某个 extension 在野外的表现;实现仍在 extensions。 | +| [`evaluation/`](../evaluation/README.md) | 评测把假设做成可复现对照;本目录只记看到了什么。观测不是评测。 | + +## 起步布局 + +先有真实记录再往下加目录,不要预埋空数据或虚构指标。 + +- [`logs/`](logs/README.md):脱敏后的 run / 使用记录 +- [`metrics/`](metrics/README.md):指标定义与仪表盘笔记 +- 本 README diff --git a/observation/logs/README.md b/observation/logs/README.md new file mode 100644 index 00000000..f24f9cb3 --- /dev/null +++ b/observation/logs/README.md @@ -0,0 +1,5 @@ +# logs/ + +脱敏后的 run / 使用记录。有真实观测再往这里写;不要预埋空日志或虚构轨迹。 + +写成 markdown,不要提交原始 `*.log`。约定见上一级 [README](../README.md)。 diff --git a/observation/metrics/README.md b/observation/metrics/README.md new file mode 100644 index 00000000..2d48916a --- /dev/null +++ b/observation/metrics/README.md @@ -0,0 +1,5 @@ +# metrics/ + +指标定义与仪表盘笔记。有真实要跟踪的量再往这里写;不要预埋虚构数字。 + +约定见上一级 [README](../README.md)。