focalpoint 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. focalpoint-0.1.0/.gitignore +5 -0
  2. focalpoint-0.1.0/0-external-baseline/ARCHITECTURE.md +151 -0
  3. focalpoint-0.1.0/0-external-baseline/PRODUCT-BASELINE.md +77 -0
  4. focalpoint-0.1.0/0-external-baseline/README.md +48 -0
  5. focalpoint-0.1.0/0-external-baseline/ROADMAP.md +96 -0
  6. focalpoint-0.1.0/1-vision/PRD-goals.md +52 -0
  7. focalpoint-0.1.0/1-vision/PRD-philosophy.md +90 -0
  8. focalpoint-0.1.0/1-vision/WhitePaper.md +374 -0
  9. focalpoint-0.1.0/2-requirements/PRD-cognitive-engine.md +281 -0
  10. focalpoint-0.1.0/2-requirements/PRD-compression-spec.md +363 -0
  11. focalpoint-0.1.0/2-requirements/PRD-context-lifecycle.md +448 -0
  12. focalpoint-0.1.0/2-requirements/PRD-cto-agent.md +347 -0
  13. focalpoint-0.1.0/2-requirements/PRD-functional.md +1159 -0
  14. focalpoint-0.1.0/2-requirements/PRD-nfr.md +64 -0
  15. focalpoint-0.1.0/2-requirements/USER-SCENARIOS.md +293 -0
  16. focalpoint-0.1.0/3-architecture/ARCHITECTURE-V3.1-outdated.md +673 -0
  17. focalpoint-0.1.0/3-architecture/ARCHITECTURE.md +322 -0
  18. focalpoint-0.1.0/3-architecture/INTERFACES.md +622 -0
  19. focalpoint-0.1.0/3-architecture/architecture-diagram.md +294 -0
  20. focalpoint-0.1.0/4-implementation/CLAUDE.md +176 -0
  21. focalpoint-0.1.0/4-implementation/ROADMAP.md +166 -0
  22. focalpoint-0.1.0/4-implementation/TASK-DECOMPOSITION.md +535 -0
  23. focalpoint-0.1.0/4-implementation/v0-acceptance.md +315 -0
  24. focalpoint-0.1.0/4-implementation/v0-task-breakdown.md +406 -0
  25. focalpoint-0.1.0/CHANGELOG.md +185 -0
  26. focalpoint-0.1.0/GLOSSARY.md +118 -0
  27. focalpoint-0.1.0/LICENSE +58 -0
  28. focalpoint-0.1.0/OVERVIEW.md +200 -0
  29. focalpoint-0.1.0/PKG-INFO +315 -0
  30. focalpoint-0.1.0/README.md +235 -0
  31. focalpoint-0.1.0/SYSTEM-CONFIG.md +104 -0
  32. focalpoint-0.1.0/clawhub-skill/fpms-memory/SKILL.md +131 -0
  33. focalpoint-0.1.0/docs/USAGE-GUIDE.md +417 -0
  34. focalpoint-0.1.0/docs/superpowers/plans/2026-03-21-m1-github-integration.md +1975 -0
  35. focalpoint-0.1.0/docs/superpowers/plans/2026-03-21-mcp-server.md +741 -0
  36. focalpoint-0.1.0/docs/superpowers/plans/2026-03-21-v1-cognitive-layer.md +871 -0
  37. focalpoint-0.1.0/fpms/__init__.py +3 -0
  38. focalpoint-0.1.0/fpms/mcp_server.py +404 -0
  39. focalpoint-0.1.0/fpms/spine/__init__.py +229 -0
  40. focalpoint-0.1.0/fpms/spine/adapters/__init__.py +6 -0
  41. focalpoint-0.1.0/fpms/spine/adapters/base.py +49 -0
  42. focalpoint-0.1.0/fpms/spine/adapters/github_adapter.py +194 -0
  43. focalpoint-0.1.0/fpms/spine/adapters/registry.py +31 -0
  44. focalpoint-0.1.0/fpms/spine/archive.py +218 -0
  45. focalpoint-0.1.0/fpms/spine/bundle.py +602 -0
  46. focalpoint-0.1.0/fpms/spine/command_executor.py +115 -0
  47. focalpoint-0.1.0/fpms/spine/dashboard.py +432 -0
  48. focalpoint-0.1.0/fpms/spine/focus.py +315 -0
  49. focalpoint-0.1.0/fpms/spine/heartbeat.py +327 -0
  50. focalpoint-0.1.0/fpms/spine/models.py +242 -0
  51. focalpoint-0.1.0/fpms/spine/narrative.py +149 -0
  52. focalpoint-0.1.0/fpms/spine/recovery.py +54 -0
  53. focalpoint-0.1.0/fpms/spine/risk.py +127 -0
  54. focalpoint-0.1.0/fpms/spine/rollup.py +157 -0
  55. focalpoint-0.1.0/fpms/spine/schema.py +96 -0
  56. focalpoint-0.1.0/fpms/spine/store.py +497 -0
  57. focalpoint-0.1.0/fpms/spine/tools.py +782 -0
  58. focalpoint-0.1.0/fpms/spine/validator.py +243 -0
  59. focalpoint-0.1.0/pyproject.toml +40 -0
  60. focalpoint-0.1.0/tests/__init__.py +0 -0
  61. focalpoint-0.1.0/tests/invariants/__init__.py +0 -0
  62. focalpoint-0.1.0/tests/invariants/conftest.py +103 -0
  63. focalpoint-0.1.0/tests/invariants/test_invariant_archive_hot_zone.py +118 -0
  64. focalpoint-0.1.0/tests/invariants/test_invariant_atomic_commit.py +153 -0
  65. focalpoint-0.1.0/tests/invariants/test_invariant_dag.py +156 -0
  66. focalpoint-0.1.0/tests/invariants/test_invariant_derived_isolation.py +118 -0
  67. focalpoint-0.1.0/tests/invariants/test_invariant_idempotency.py +127 -0
  68. focalpoint-0.1.0/tests/invariants/test_invariant_status_machine.py +206 -0
  69. focalpoint-0.1.0/tests/invariants/test_invariant_xor.py +132 -0
  70. focalpoint-0.1.0/tests/test_adapter_base.py +125 -0
  71. focalpoint-0.1.0/tests/test_adapter_registry.py +64 -0
  72. focalpoint-0.1.0/tests/test_archive.py +508 -0
  73. focalpoint-0.1.0/tests/test_bundle.py +747 -0
  74. focalpoint-0.1.0/tests/test_bundle_cross_source.py +199 -0
  75. focalpoint-0.1.0/tests/test_dashboard.py +696 -0
  76. focalpoint-0.1.0/tests/test_e2e.py +648 -0
  77. focalpoint-0.1.0/tests/test_focus.py +668 -0
  78. focalpoint-0.1.0/tests/test_github_adapter.py +206 -0
  79. focalpoint-0.1.0/tests/test_heartbeat.py +625 -0
  80. focalpoint-0.1.0/tests/test_m1_e2e.py +249 -0
  81. focalpoint-0.1.0/tests/test_mcp_server.py +212 -0
  82. focalpoint-0.1.0/tests/test_models.py +199 -0
  83. focalpoint-0.1.0/tests/test_narrative.py +208 -0
  84. focalpoint-0.1.0/tests/test_recovery.py +522 -0
  85. focalpoint-0.1.0/tests/test_risk.py +405 -0
  86. focalpoint-0.1.0/tests/test_rollup.py +371 -0
  87. focalpoint-0.1.0/tests/test_schema.py +163 -0
  88. focalpoint-0.1.0/tests/test_store.py +455 -0
  89. focalpoint-0.1.0/tests/test_tools.py +769 -0
  90. focalpoint-0.1.0/tests/test_v1_e2e.py +523 -0
  91. focalpoint-0.1.0/tests/test_validator.py +490 -0
@@ -0,0 +1,5 @@
1
+ .DS_Store
2
+ __pycache__/
3
+ *.pyc
4
+ data/
5
+ fpms/narratives/task-*.md
@@ -0,0 +1,151 @@
1
+ # Architecture Baseline
2
+
3
+ ## 总体架构
4
+
5
+ ```
6
+ GitHub / Notion / Telegram
7
+
8
+
9
+ Adapters / Sync Layer
10
+
11
+
12
+ FounderOS Cognitive Core
13
+ - local graph
14
+ - summaries
15
+ - focus
16
+ - alerts
17
+ - compression
18
+ - bundle assembly
19
+
20
+
21
+ Founder / Agent
22
+ ```
23
+
24
+ ## 设计立场
25
+
26
+ FounderOS 不拥有完整业务事实。
27
+
28
+ FounderOS 拥有的是“认知层状态”:跨工具关系、压缩记忆、焦点、提醒、上下文编排。
29
+
30
+ ## 本地存什么
31
+
32
+ 本地 SQLite 或本地文件只保存以下内容:
33
+ - `node_ref`
34
+ - `node_id`
35
+ - `source`
36
+ - `source_id`
37
+ - `source_url`
38
+ - `cognitive_fields`
39
+ - `why`
40
+ - `summary`
41
+ - `next_step`
42
+ - `owner_override`(仅当外部没有统一 owner)
43
+ - `graph`
44
+ - `parent_id`
45
+ - `depends_on`
46
+ - `runtime`
47
+ - `focus_list`
48
+ - `stash`
49
+ - `last_alerts`
50
+ - `compression`
51
+ - `compressed_summary`
52
+ - `last_compressed_at`
53
+ - `no_llm_compression`
54
+ - `sync_cache`
55
+ - `cached_title`
56
+ - `cached_status`
57
+ - `source_synced_at`
58
+ - `source_deleted`
59
+
60
+ ## 不本地重复存什么
61
+
62
+ 默认不把以下内容作为本地主事实源:
63
+ - 外部工具的任务主状态
64
+ - 外部正文全文
65
+ - 外部评论全文
66
+ - 外部附件
67
+ - 外部审计全历史
68
+
69
+ 需要时可以缓存,但缓存只用于:
70
+ - 降级读取
71
+ - token 裁剪
72
+ - 最近一次同步快照
73
+
74
+ ## 读路径
75
+
76
+ 1. 选择当前 focus。
77
+ 2. 读取本地认知层数据。
78
+ 3. 对 focus 及其近邻节点实时拉取外部快照。
79
+ 4. 本地认知层与外部快照合并。
80
+ 5. 组装 L0 / L_Alert / L1 / L2。
81
+ 6. 注入 Agent prompt 或返回 Founder 查看。
82
+
83
+ ## 写路径
84
+
85
+ ### 写本地
86
+
87
+ FounderOS 直接写本地认知层:
88
+ - why
89
+ - summary
90
+ - depends_on
91
+ - parent
92
+ - focus
93
+ - alerts dedup
94
+ - compressed_summary
95
+
96
+ ### 写外部
97
+
98
+ FounderOS 只在以下场景写回外部:
99
+ - append comment / report
100
+ - write decision summary
101
+ - 明确授权的状态同步
102
+
103
+ 默认策略:
104
+ - comment 写回可以先做
105
+ - status 双向同步后做
106
+ - 永远不要默认覆盖外部正文
107
+
108
+ ## 同步策略
109
+
110
+ - 常规轮询:15 分钟
111
+ - focus 实时刷新:开启
112
+ - 同步失败:读取缓存并标记“可能过时”
113
+ - 外部删除:本地保留认知层,但标记 `source_deleted=true`
114
+
115
+ ## 核心模块
116
+
117
+ - `adapters/`
118
+ GitHub / Notion / Telegram 连接层
119
+ - `sync/`
120
+ 轮询、缓存、状态映射、降级
121
+ - `graph/`
122
+ cross-tool parent / dependency
123
+ - `memory/`
124
+ summary / why / compressed_summary
125
+ - `attention/`
126
+ focus / stash / alert dedup
127
+ - `bundle/`
128
+ Context Bundle 组装
129
+ - `writeback/`
130
+ comment / summary 写回外部
131
+
132
+ ## 最重要的不变量
133
+
134
+ 1. 外部工具状态是事实源,本地镜像不是。
135
+ 2. 本地 graph 与 cognitive fields 是 FounderOS 的核心资产。
136
+ 3. 缓存丢失可以重建,graph 与 why 不可以随意覆盖。
137
+ 4. 外部写回失败不影响本地认知层一致性。
138
+ 5. Adapter 不可用时,系统降级但不应完全不可用。
139
+
140
+ ## v1 只做哪些外部工具
141
+
142
+ - GitHub: 任务与代码执行主状态
143
+ - Notion: 文档与方案上下文
144
+ - Telegram: Founder 交互入口与提醒触达
145
+
146
+ ## 暂不做
147
+
148
+ - 双向强一致状态同步
149
+ - 多人协作权限系统
150
+ - 外部工具全文镜像仓库
151
+ - 通用 RAG 平台
@@ -0,0 +1,77 @@
1
+ # Product Baseline
2
+
3
+ ## 一句话
4
+
5
+ FounderOS 是外部工具之上的认知层与控制层。
6
+
7
+ 它不负责替代 GitHub、Notion、Telegram;它负责把这些工具里的信息变成 Agent 和 Founder 都能直接工作的“认知工作台”。
8
+
9
+ ## 核心问题
10
+
11
+ 我们要解决的不是任务 CRUD,而是以下问题:
12
+
13
+ 1. Agent 跨 session 后,无法快速恢复对项目与决策脉络的理解。
14
+ 2. 信息分散在多个工具里,Agent 和 Founder 需要手动拼接上下文。
15
+ 3. 外部工具能存事实,但不能表达跨工具因果链、依赖关系和注意力优先级。
16
+ 4. 长周期项目会被遗忘,缺少跨工具的主动提醒和异常上报。
17
+ 5. Founder 需要的是控制能力,不是再维护一套新的任务系统。
18
+
19
+ ## 产品边界
20
+
21
+ | 能力 | 外部工具负责 | FounderOS 负责 |
22
+ |------|-------------|----------------|
23
+ | 任务主状态 | GitHub Projects / Issue / Notion DB | 读取、映射、缓存,不作为主事实源 |
24
+ | 文档正文 | Notion / GitHub / 外部文档系统 | 摘要、压缩、上下文抽取 |
25
+ | 评论与讨论 | GitHub / Telegram / Notion comments | 跨工具聚合、决策提炼、必要时写回 |
26
+ | 跨工具依赖 | 无统一承载者 | FounderOS 本地维护 |
27
+ | why / summary / focus | 外部工具通常没有统一模型 | FounderOS 本地维护 |
28
+ | Anti-Amnesia / Heartbeat | 单工具局部提醒 | FounderOS 跨工具提醒 |
29
+ | Founder 控制入口 | Telegram / Agent 对话 | FounderOS 负责解释、校验、编排 |
30
+
31
+ ## 数据归属
32
+
33
+ ### 外部工具是事实源
34
+
35
+ 以下信息默认以外部工具为准:
36
+ - title
37
+ - status
38
+ - assignee / owner(如果外部已有)
39
+ - 正文内容
40
+ - 评论历史
41
+ - 原始更新时间
42
+
43
+ ### FounderOS 是认知源
44
+
45
+ 以下信息由 FounderOS 自己维护:
46
+ - cross-tool parent / dependency 关系
47
+ - why
48
+ - summary
49
+ - next_step
50
+ - focus / stash / alert dedup
51
+ - compressed_summary
52
+ - sync cache 与 stale 标记
53
+ - Founder/Agent 的决策摘要
54
+
55
+ ## 关键原则
56
+
57
+ 1. 外部工具优先,不重造轮子。
58
+ 2. FounderOS 只存外部工具存不了、算不出来、拼不起来的东西。
59
+ 3. 外部状态可以缓存,但缓存不是事实源。
60
+ 4. 写回外部是能力,不是前提。
61
+ 5. 本地认知层必须可审计、可回滚、可降级。
62
+
63
+ ## 非目标
64
+
65
+ - 自建新的任务管理 UI
66
+ - 自建新的文档编辑器
67
+ - 自建新的聊天系统
68
+ - 把所有业务状态重新迁移进本地数据库
69
+ - 在 v0/v1 做多 Office 自动化公司操作系统
70
+
71
+ ## v1 成功标准
72
+
73
+ - Founder 能在 5 分钟内看到跨工具全局状态与重点风险。
74
+ - Agent 能围绕焦点任务自动组装跨工具 Context Bundle。
75
+ - 关键依赖和 why 不再散落在多个工具里只能靠人脑记忆。
76
+ - 外部工具短暂不可用时,系统可降级为缓存读取而不瘫痪。
77
+ - Founder 不需要为系统再维护一套平行任务数据。
@@ -0,0 +1,48 @@
1
+ # External-First Baseline
2
+
3
+ 这组文档定义 FounderOS/FPMS 的当前主线:
4
+
5
+ **外部工具是事实源,FounderOS 是认知层与控制层。**
6
+
7
+ 旧文档不删除,但从现在开始,凡是与本文件夹冲突的内容,**以本文件夹为准**。
8
+
9
+ ## 这组文档解决什么问题
10
+
11
+ 我们不再优先解决“如何自研一个项目管理系统”。
12
+
13
+ 我们优先解决的是:
14
+ - Agent 跨 session 的认知连续性
15
+ - 跨 GitHub / Notion / Telegram 的上下文组装
16
+ - 跨工具因果链、依赖链和焦点管理
17
+ - 关键提醒、Anti-Amnesia 和中途校验
18
+ - Founder 的自然语言控制与审计
19
+
20
+ ## 这组文档不做什么
21
+
22
+ - 不重写 GitHub / Notion 的任务和文档 UI
23
+ - 不自建完整任务录入和看板系统
24
+ - 不把 FounderOS 做成新的知识库或聊天工具
25
+ - 不要求先做完 standalone FPMS 再验证价值
26
+
27
+ ## 文件说明
28
+
29
+ - `README.md`
30
+ 这组文档的入口与优先级说明
31
+ - `PRODUCT-BASELINE.md`
32
+ 产品边界、问题定义、能力归属、非目标
33
+ - `ARCHITECTURE.md`
34
+ 外部工具为事实源时的系统设计
35
+ - `ROADMAP.md`
36
+ 外部优先路线下的分阶段交付计划
37
+
38
+ ## 文档优先级
39
+
40
+ 1. 本文件夹中的文档
41
+ 2. `/2-requirements/PRD-cognitive-engine.md`
42
+ 3. 其他历史文档(仅供参考)
43
+
44
+ ## 一句话定义
45
+
46
+ FounderOS 不是新的项目管理工具。
47
+
48
+ FounderOS 是架在外部工具之上的认知层与控制层:它连接事实、压缩历史、组装上下文、分配注意力,并帮助 Founder 与 Agent 做出更好的决策。
@@ -0,0 +1,96 @@
1
+ # Roadmap
2
+
3
+ ## 路线原则
4
+
5
+ 我们不先做一个完整的 standalone FPMS,再去接外部工具。
6
+
7
+ 我们从第一阶段就按“外部工具为事实源”实现。
8
+
9
+ ## Phase 0 — 文档与模型收口
10
+
11
+ 目标:统一产品边界和数据归属。
12
+
13
+ 交付物:
14
+ - 本文件夹 4 份基线文档
15
+ - 统一术语:FPMS = cognitive layer,不再定义为 project management engine
16
+ - 统一数据归属表
17
+ - 统一同步与降级策略
18
+
19
+ 验收:
20
+ - 新 agent 只读本文件夹即可理解当前主线
21
+ - 与旧文档冲突时有明确裁决规则
22
+
23
+ ## Phase 1 — GitHub-first Cognitive MVP
24
+
25
+ 目标:先围绕 GitHub 建立最小认知闭环。
26
+
27
+ 交付物:
28
+ - GitHub Adapter
29
+ - 本地 node_ref + graph + summary/why 存储
30
+ - focus + heartbeat + L0/L1/L2 bundle
31
+ - comment 写回能力
32
+ - 缓存降级能力
33
+
34
+ 验收:
35
+ - 给定一个 GitHub issue,FounderOS 能拉状态、补 why、建立依赖、组装 context
36
+ - GitHub 短暂不可用时,仍能用缓存继续工作
37
+ - Founder 可以通过 Telegram/Agent 查看重点任务与风险
38
+
39
+ ## Phase 2 — Notion Context Integration
40
+
41
+ 目标:把文档上下文接进来,而不是只看任务状态。
42
+
43
+ 交付物:
44
+ - Notion Adapter
45
+ - 跨 GitHub / Notion 的 context merge
46
+ - 决策摘要与文档压缩
47
+ - cross-tool dependency 支持
48
+
49
+ 验收:
50
+ - 焦点任务的 context 中同时出现 GitHub 状态和 Notion 决策材料
51
+ - Agent 可以解释“现在做什么”和“为什么这么做”
52
+
53
+ ## Phase 3 — Telegram Control Layer
54
+
55
+ 目标:让 Founder 真正通过自然语言控制,而不是手动翻工具。
56
+
57
+ 交付物:
58
+ - Telegram 交互协议
59
+ - 告警推送
60
+ - shift_focus / explain / summarize / report
61
+ - 中途校验与退出上报
62
+
63
+ 验收:
64
+ - Founder 用 Telegram 就能看到重点风险、切换焦点、收到异常上报
65
+ - Agent 的关键发现能推送给 Founder,而不是留在某个工具角落里
66
+
67
+ ## Phase 4 — Writeback and Reliability
68
+
69
+ 目标:把系统从“只读认知层”升级成“有限闭环认知层”。
70
+
71
+ 交付物:
72
+ - comment / summary 写回外部
73
+ - 状态映射配置化
74
+ - 重试队列与离线恢复
75
+ - Assembly Trace 可观测性
76
+
77
+ 验收:
78
+ - 退出上报可稳定写回 GitHub / Notion
79
+ - 网络抖动时请求不丢失
80
+ - 可以解释某次 context 是如何被组装出来的
81
+
82
+ ## 明确不做的顺序
83
+
84
+ 以下事情不应排在前面:
85
+ - 自建任务管理 UI
86
+ - 自建完整状态机并要求所有业务迁移进来
87
+ - 先做多 Office 自动化再验证单 Founder 工作流
88
+ - 先做全量本地知识库再验证 context bundle 价值
89
+
90
+ ## 当前推荐优先级
91
+
92
+ 1. GitHub-first cognitive MVP
93
+ 2. Notion context integration
94
+ 3. Telegram control layer
95
+ 4. 写回与可靠性
96
+ 5. 多 Office 与更高层自动化
@@ -0,0 +1,52 @@
1
+ # 3. 目标
2
+
3
+ ## 3.1 核心目标
4
+
5
+ 本系统要解决的不是"项目管理软件"的问题,而是"AI Agent 如何在跨 Session 场景下持续、高效、可控地管理复杂项目群"的问题。
6
+
7
+ ### G1. 跨 Session 认知连续性
8
+
9
+ Agent 每次唤醒时,能在**秒级**(而非分钟级)恢复对所有项目的全局认知——包括当前状态、关键卡点、待办优先级和近期决策脉络。消除"每次对话从零开始"的根本瓶颈。
10
+
11
+ ### G2. 最小充分上下文注入
12
+
13
+ 系统根据当前任务自动组装**最高信噪比**的认知包(Context Bundle),精准推送给 Agent。不多不少——既不因信息缺失导致错误决策,也不因冗余加载浪费注意力和算力。
14
+
15
+ ### G3. 确定性与概率性解耦
16
+
17
+ 所有可由规则稳定计算的工作(状态流转、依赖冒泡、死锁检测、投影生成)由底层脊髓引擎确定性完成,**系统正确性不依赖 LLM**。大模型仅负责业务理解、策略判断和自然语言输出。
18
+
19
+ ### G4. 全局视图始终准确
20
+
21
+ 任何节点的状态变更,自动沿依赖图谱向上冒泡,保持全局看板、项目摘要和父节点状态**近实时一致且可重建**。无需人工维护,无需 Agent 逐层手动更新。
22
+
23
+ ### G5. 分形可扩展
24
+
25
+ 从原子任务到跨业务线的战略目标群,系统使用统一核心 Schema 与同一套引擎。结构应随业务增长保持可控扩展,避免因节点层级和依赖关系增长而导致复杂度失控。
26
+
27
+ ### G6. 次用户(人类监督者)体验
28
+
29
+ 人类监督者无需学习任何命令或语法:
30
+ - **自然语言交互**:说人话即可下达指令和查询
31
+ - **全局可见性**:随时掌握所有项目的进展、风险、卡点
32
+ - **数据主权**:系统数据可审计、可导出、可回滚;叙事内容以 Markdown 保存,结构化状态以 SQLite 管理,关键变更可通过 Git 或事件日志追踪
33
+
34
+ ### G7. 成本可控(FinOps)
35
+
36
+ 系统级 token 管理开销(Context Bundle 组装 + 全局投影)占单次 Agent 调用总 token 的比例可量化、可优化。避免因项目管理上下文无节制膨胀导致 API 成本失控。
37
+
38
+ ### G8. 可恢复性
39
+
40
+ 所有全局视图、焦点列表与认知包都必须可由事实源重建。系统在任意时刻都可恢复到一致状态——派生视图损坏不影响数据完整性,重建即可修复。其中,结构化状态与关系以 SQLite 为事实源,叙事历史以 Markdown 为事实源;所有摘要、投影与认知包均为派生物,不构成第二真相源。
41
+
42
+ ## 3.2 非目标(v1 不做)
43
+
44
+ | 非目标 | 原因 |
45
+ |--------|------|
46
+ | 可视化仪表盘(Dashboard) | v1 聚焦 Agent 内部认知引擎;人类监督通过自然语言 Tool Call 实现,无需独立 UI 层 |
47
+ | 多人协作 / 权限管理 | v1 限定为单 Agent + 单人类监督者场景,不引入 RBAC、并发控制或多用户同步机制 |
48
+ | ~~外部工具集成~~ | ~~已移入核心目标~~。认知引擎从第一天就通过 Adapter 集成 GitHub/Notion/Telegram,详见 PRD-cognitive-engine |
49
+ | 自动化工作流引擎 | 认知引擎仅负责认知层(因果链、Context 组装、记忆压缩),不内建触发-动作规则链或工作流编排层 |
50
+ | 自然语言解析器 | 完全复用宿主 Agent(OpenClaw)的 LLM Tool 解析能力;认知引擎不重复构建 NLP 层 |
51
+ | 多 Agent 协调 | v1 设计为单 Agent 架构;多 Agent 协调、状态同步与冲突解决机制留待后续版本 |
52
+ | 自动决策代理 | 认知引擎可主动告警(如卡点、超期),但不自动执行业务决策或替用户推进项目。业务决策权保留给人类监督者或宿主 Agent 策略层 |
@@ -0,0 +1,90 @@
1
+ # 2. 设计哲学:向人类认知学习
2
+
3
+ ## 2.1 人类 Context 管理机制及启示
4
+
5
+ 人类能在有限工作记忆下处理复杂任务,不是因为记得多,而是因为具备高效的认知压缩、注意力分配和外部记忆协作能力。本系统借鉴其中最有效的机制,将其转化为 Agent 可执行的系统能力。
6
+
7
+ | 人类机制 | 原理 | 可借鉴度 | 系统设计启示(认知引擎系统级补偿) |
8
+ |----------|------|----------|-------------------------------|
9
+ | **分块(Chunking)** | 工作记忆 4-7 块,每块可压缩复杂概念 | ✅ 完全映射 | 每个节点是一个认知块,一句话摘要即可恢复对该节点的认知 |
10
+ | **叙事(Narrative)** | 故事比清单好记 10 倍,天然携带因果链 | ✅ 完全映射 | Context 以时间线叙事体组织,保留因果链和决策背景,绝不用无序 bullet |
11
+ | **遗忘(Forgetting)** | 主动过滤噪音,是功能不是 bug | ✅ 机制模拟 | 已 Done 且无入度依赖的节点自动降权冷冻,保持工作区 Index 纯净 |
12
+ | **周期回顾(Rehearsal)** | 周会/复盘对抗遗忘曲线 | ✅ 机制模拟 | Heartbeat = 系统替 Agent 开的「数字周会」,主动揪出风险项 |
13
+ | **外化(Externalization)** | 承认记不住,借助笔记/日历/看板 | ✅ 完全映射 | 本地文件系统(SQLite+MD)+ 全局概览 = Agent 的外化「数字白板」 |
14
+ | **关联触发(Association)** | 线索触发记忆链,一环拉出一长串 | ⚠️ 系统代偿 | Agent 无直觉,靠底层 DAG 图计算引擎实现确定性关系推导补偿 |
15
+ | **聚焦(Focus)** | 任何时刻只深度关注一件事 | ✅ 机制模拟 | 焦点节点加载 100% 全量上下文,其余物理降级为一句话摘要 |
16
+ | **联想打包(Bundling)** | focus 时大脑自动拉入相关背景 | ⚠️ 控制反转 | 摒弃 Agent 主动检索。由脊髓引擎将 parent/依赖方拼装打包,直接喂给 Agent |
17
+ | **视觉分辨率(Foveal)** | 注视点高清,周边模糊但画面完整 | ⚠️ 机制模拟 | 焦点=中央凹(全量),近景=周边视觉(摘要),全局看板=整体大盘永不丢失 |
18
+
19
+ ## 2.2 大模型与人类大脑的关键差异
20
+
21
+ 设计不应只学习人类认知的优点,也必须正视 Agent 与人类在记忆机制上的根本差异。
22
+
23
+ | 维度 | 人类(碳基大脑) | 我们的智能体系统(LLM + 底层基建) |
24
+ |------|-----------------|----------------------------------|
25
+ | Session 内记忆 | 极有限(4-7 chunks) | 极强(1M+ window),且通过多分辨率受控 |
26
+ | 跨 Session 记忆 | 持续存在,模糊但不消失 | 通过本地文件与数据库图谱实现物理持久化 |
27
+ | 检索方式 | 关联触发,潜意识自动浮现 | 摒弃工具摸黑搜索,采用确定性主动推流(DCP)极速注入 |
28
+ | 遗忘 | 自动、智能、情绪加权 | 基于图谱入度规则与时间衰减的强制冷冻 |
29
+ | 压缩 | 无意识自动完成 | 需要显式设计(如小模型异步跑批处理压缩) |
30
+ | 背景意识 | 模糊但持续在线 | 通过三层分辨率(焦点/近景/背景看板)强行构建 |
31
+ | 聚焦 | 自动、直觉驱动 | 需要底层状态机(Deadline/卡点)进行中断与强制调度 |
32
+
33
+ ### 核心洞察
34
+
35
+ 1. **人类有持续的背景意识,LLM 要么全知要么全盲。** 系统必须用「多分辨率眼球模型」弥补这个根本差异。
36
+ 2. **人类天生知道"现在最该关注什么",LLM 没有这个直觉。** 必须通过底层心跳或显式指令强制分配注意力。
37
+ 3. **人类的注意力像眼球——注视点高清,周边模糊,但整体画面永不丢。** 系统需要「全量叙事 / 状态摘要 / 一句话标题」的连续分辨率梯度,而非「加载或不加载」的二元开关。
38
+ 4. **人类 focus 时大脑自动联想打包,LLM 不会。** 必须由底层代码(脊髓)代为完成图谱遍历,构建好「认知包(Context Bundle)」直接推给 LLM,绝不能让 Agent 浪费算力去自己 Pull。
39
+
40
+ ## 2.3 硅基 vs 碳基:系统的独特优势
41
+
42
+ > 注意:这里的优势不单指 Agent(LLM),而是指「LLM 大脑 + 结构化底层系统」的完整混合体。
43
+
44
+ | 维度 | 人类(碳基) | 智能体系统(硅基混合体) |
45
+ |------|-------------|------------------------|
46
+ | 回忆精度 | 模糊、会变形、会自我编造 | 100% 精确,写下即可万次无损读取 |
47
+ | 并行逻辑 | 极弱(心算超过 3 步必错) | LLM 极弱,但底层代码状态机可 100% 严谨地瞬间完成几十个节点的级联冒泡 |
48
+ | 结构化处理 | 费劲,极度消耗精力 | 机器天然擅长遍历 DAG,对 YAML/SQL 读写如飞 |
49
+ | 情绪偏差 | 焦虑与疲惫会扭曲判断 | 纯粹基于权重和 Deadline 数学规则执行 |
50
+
51
+ ### 终极推论:为什么少数精准 Chunk 胜过海量原始数据
52
+
53
+ 人类只有 4-7 个 chunk 就能完成极其复杂的任务。不是因为记得多,而是因为**每一块都是精准的、高度抽象的**。
54
+
55
+ 外科医生做手术时脑子里不是整本解剖学教科书,而是精确到这一刀需要的那几个关键信息。Agent 应该追求同样的精准度。
56
+
57
+ **这个类比可以精确展开:**
58
+
59
+ | 维度 | 外科医生(人类认知) | 认知引擎(Agent 认知) |
60
+ |------|---------------------|------------------------|
61
+ | 手术前 | 阅读完整病历、影像、化验报告 | 底层脊髓引擎遍历完整图谱、依赖链、历史日志 |
62
+ | 手术中脑子里有什么 | 只有这一刀的关键坐标:切入点、避让神经、止血位 | 只有当前任务的认知包:焦点节点全量 + 依赖摘要 + 风险标记 |
63
+ | 手术中脑子里没有什么 | 不会回想昨天的晚餐、不会翻阅教科书第3章 | 不会加载已归档节点、不会塞入无关项目的历史 |
64
+ | 关键信息从哪来 | 护士递器械、麻醉师报数据——**被投喂,不是自己找** | 脊髓引擎打包推送——**DCP,不是 RAG Pull** |
65
+ | 全局画面 | 余光看监护仪(心率、血压、血氧)——模糊但持续在线 | 背景看板(全局概览)——一句话状态,永不丢失 |
66
+
67
+ **为什么这种"精准提纯"在百万 Token 时代反而更重要:**
68
+
69
+ 1. **注意力是零和博弈。** Transformer 的 Softmax 注意力权重总和恒等于 1。塞入的 token 越多,每个关键 token 分到的注意力权重越低。这是数学,不会因为窗口变大而消失。无关信息不是中性背景板——它是物理层面的认知干扰弹。
70
+
71
+ 2. **"找得到"不等于"想得清"。** 模型能在 1M token 里找到一根针(检索),不代表它能在 1M token 的噪声里完成多步因果推理。检索和推理是完全不同的认知任务,后者对信噪比的要求高几个数量级。
72
+
73
+ 3. **延迟是物理墙。** Agent 的核心是高频 OODA 循环(感知→思考→行动→观察)。每次循环的 TTFT(首字延迟)与输入长度正相关。塞满 1M 意味着每次思考前要等几十秒——系统瘫痪。
74
+
75
+ 4. **成本是线性的。** 输入 token 成本与长度线性相关。Agent 每天执行上百次循环,无差别塞满 vs 精准提纯,年成本可能差 100 倍。
76
+
77
+ 5. **1M 是仓库容量,不是工作台面积。** 长上下文的真正价值在于"可访问全集"(低频精读一本厚书),不在于"每次循环都把全集塞进大脑正中央"。真正送进推理核心的,仍然是小而精的认知包。
78
+
79
+ **因此,系统的使命是:**
80
+
81
+ > 在当前任务下,以最小必要上下文,提供最高信噪比、可推理、可执行的认知包。Memory 系统的本质不是存储——存储已经不稀缺了——而是**注意力分配**。
82
+
83
+ ## 2.4 设计原则
84
+
85
+ 1. **控制反转(IoC)** — Agent 是被投喂者,不是检索者。数据找人,而不是人找数据。所有依赖梳理、状态冒泡、卡点打包,全由确定性底层系统算好,直接以极简格式推给 Agent。
86
+ 2. **最小充分上下文(Minimum Sufficient Context)** — 每次只注入当前任务恰好需要的信息量,不多不少。1M context 是仓库容量,不是工作台面积。优化目标是每个 token 的信息密度,不是总量上限。注入量按任务难度弹性伸缩(最小 5k → 20k → 200k → 500k → 1M),当大预算精度不够时逐级缩减、聚焦信噪比。具体分级见 SYSTEM-CONFIG。
87
+ 3. **精准胜于全面** — 结构化精准 Context 永远优于泛泛 RAG 碎片,无论窗口多大。Context window 增长的红利应用于更深度的思考,而不是囤积更多冗余。
88
+ 4. **抽象是系统的生命线** — 节点摘要质量 = 系统效率上限。必须有机制持续将冗长旧日志压缩为一句话背景。
89
+ 5. **分形自相似(Fractal)** — 从原子任务到公司战略目标,全部采用同一套 Schema,无限嵌套,降低系统解析复杂度。
90
+ 6. **算力与模式解耦(Brain-Spine Model)** — 绝不用概率模型做确定性算术题。概览大盘与执行链路物理隔离;死锁拦截与状态流转交由底层代码(脊髓)瞬间完成,大模型(大脑)仅负责业务策略的阅读与战术输出。