code_repo_wiki/model/
document.rs

1use serde::{Deserialize, Serialize};
2
3/// 文档类型
4#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
5pub enum DocumentKind {
6    /// Knowledge Card（给 AI Agent 的结构化摘要）
7    KnowledgeCard,
8    /// Wiki Page（给人类的叙述性文档）
9    WikiPage,
10    /// 架构概览
11    ArchitectureOverview,
12    /// 项目概览（overview.md，独立于模块页生成）
13    ///
14    /// 决策：DocumentKind 是纯枚举（无 architecture 等可复用字段），
15    /// 且 output::wiki_page_path 按 kind 特判文件名（架构概览→architecture.md），
16    /// 因此新增独立变体而非复用 ArchitectureOverview，避免概览写错文件名。
17    ProjectOverview,
18    /// 目录
19    TableOfContents,
20    /// API 参考（按模块分组列出公开实体）
21    ApiReference,
22    /// 数据库 Schema 文档（基于 SQL 建表语句生成）
23    DatabaseSchema,
24}
25
26/// Wiki 文档
27#[derive(Debug, Clone, Serialize, Deserialize)]
28pub struct WikiDocument {
29    pub title: String,
30    pub kind: DocumentKind,
31    pub content: String,
32    /// 文档语言（多语言独立生成时写入对应语言目录）
33    pub language: String,
34    pub module_path: Vec<String>,
35    /// 交叉引用链接
36    pub references: Vec<Reference>,
37    /// 最后更新时间（ISO 8601）
38    pub last_updated: String,
39    /// 基于的 git 提交短哈希（v32 10.2 基线行）
40    ///
41    /// 取值 = 生成时 HEAD 提交短哈希（前 8 位）；非 git 仓库或无 HEAD
42    /// 时为 None（渲染端省略「基于提交」行）。HEAD 是**非易变信号**——
43    /// 同一提交下多次生成值不变，不破坏 test_determinism 的内容级哈希；
44    /// 与 llms_txt.rs「内容禁止注入易变时间戳/基线」契约的取舍：时间戳
45    /// 每次生成都变（必须归一化），提交哈希只在代码变更时变（恰是页面
46    /// 内容应当变化的时刻）。仅供人工核对产物对应的源码版本。
47    pub based_on_commit: Option<String>,
48    /// 源文件指纹（用于增量更新检测）
49    pub fingerprint: Option<String>,
50}
51
52/// 交叉引用
53#[derive(Debug, Clone, Serialize, Deserialize)]
54pub struct Reference {
55    pub target_title: String,
56    pub target_path: String,
57    pub relation: String,
58}
59
60/// Knowledge Card（给 AI Agent 的结构化格式）
61#[derive(Debug, Clone, Serialize, Deserialize)]
62pub struct KnowledgeCard {
63    pub module_name: String,
64    pub module_type: String,
65    pub summary: String,
66    pub key_entities: Vec<EntitySummary>,
67    pub dependencies: Vec<String>,
68    pub dependents: Vec<String>,
69    pub design_patterns: Vec<String>,
70    pub todo_notes: Vec<String>,
71    /// 关联的源文件路径（由 chunk 直接填充，不经过 LLM）
72    #[serde(default)]
73    pub related_files: Vec<String>,
74    /// 编码规范（LLM 生成的描述性字段）
75    #[serde(default)]
76    pub coding_spec: Option<String>,
77    /// 技术栈（LLM 生成的描述性字段）
78    #[serde(default)]
79    pub tech_stack: Vec<String>,
80    /// 架构说明（LLM 生成的描述性字段）
81    #[serde(default)]
82    pub architecture: Option<String>,
83    /// 人工修改反向同步记录：被人工编辑的文档路径 + 内容摘要，
84    /// 下次生成时作为 LLM 输入提示（"有人工修改待同步"）
85    #[serde(default)]
86    pub pending_manual_edits: Vec<String>,
87    /// 本模块涉及的实体级特征名（演进计划 T3.3：特征追溯，
88    /// 由生成管道从 graph.features 与模块实体的交集回填，不经过 LLM）
89    #[serde(default)]
90    pub features: Vec<String>,
91}
92
93/// 实体摘要（用于 Knowledge Card）
94#[derive(Debug, Clone, Serialize, Deserialize)]
95pub struct EntitySummary {
96    pub name: String,
97    pub kind: String,
98    pub visibility: String,
99    pub doc: Option<String>,
100    /// 反向链接：源码定位 "文件路径:起始行-结束行"（演进计划 T3.3，
101    /// 由生成管道从 chunk 实体回填，不经过 LLM）
102    #[serde(default)]
103    pub source: Option<String>,
104}
code_repo_wiki/model/document.rs

code_repo_wiki/model/
document.rs
