diff --git a/Project/fonrey/UI_SYSTEM/UI_SYSTEM.md b/Project/fonrey/UI_SYSTEM/UI_SYSTEM.md index df997a95..d8b2f0d9 100644 --- a/Project/fonrey/UI_SYSTEM/UI_SYSTEM.md +++ b/Project/fonrey/UI_SYSTEM/UI_SYSTEM.md @@ -1,6 +1,6 @@ # Fonrey UI System 设计规范 -**版本**：v1.1 +**版本**：v1.2 **最后更新**：2026-04-25 **维护者**：UI/UX 架构组 **适用技术栈**：Tailwind CSS + HTMX + Alpine.js + Django 模板 @@ -966,50 +966,288 @@ Flatpickr 自定义样式覆盖见附录 10.3。 ### 5.1 整体框架 ``` -┌──────────────────────────────────────────────────────────────┐ -│ 顶部导航 Topbar（56px） │ -│ [Logo 150px] [全局搜索 360px] [消息] [帮助] [头像▾] │ -├────────────┬─────────────────────────────────────────────────┤ -│ │ 面包屑 [次要操作] [主操作] │ -│ 侧边导航 │ ┌─────────────────────────────────────────────┐ │ -│ Sidebar │ │ 页面标题 H1 │ │ -│ 240px │ ├─────────────────────────────────────────────┤ │ -│ 可折叠 │ │ 筛选 / 工具栏（Sticky） │ │ -│ → 64px │ ├─────────────────────────────────────────────┤ │ -│ │ │ │ │ -│ │ │ 内容主体 │ │ -│ │ │ │ │ -│ │ └─────────────────────────────────────────────┘ │ -└────────────┴─────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────────────┐ +│ Topbar（56px，sticky top-0 z-20） │ +│ [Logo 150px] [主导航: 主页 房源 客源 营销 交易 数据 人事 系统] │ +│ [消息🔔] [帮助?] [头像▾] │ +├─────────────────┬────────────────────────────────────────────────────┤ +│ Sidebar │ 内容区（Content Area） │ +│ 展开 240px │ 面包屑 > 房源管理 > 二手 & 租赁 [次操作] [主操作] │ +│ 折叠 64px │ ───────────────────────────────────────────────── │ +│ │ 页面标题 H1 │ +│ [当前主分类 │ ───────────────────────────────────────────────── │ +│ 的子菜单] │ 筛选 / 工具栏（Sticky，top-14） │ +│ │ ───────────────────────────────────────────────── │ +│ ← 折叠按钮 │ 内容主体（表格 / 卡片 / 表单） │ +│ │ │ +│ │ 分页栏 │ +└─────────────────┴────────────────────────────────────────────────────┘ ``` -- **Topbar 高度**：56px，`h-14`，`bg-white border-b border-neutral-200 sticky top-0 z-20` -- **Sidebar 宽度**：展开 240px (`w-60`) / 折叠 64px (`w-16`)；Alpine.js 控制，状态持久化到 `localStorage` -- **内容区左内边距**：展开态 `ml-60`，折叠态 `ml-16`，配合 `transition-all` -- **主内容区内边距**：`px-6 py-4` +**尺寸约定** -### 5.2 侧边栏（Sidebar） +| 区域 | 规格 | +|---|---| +| Topbar 高度 | 56px（`h-14`）；`sticky top-0 z-20` | +| Sidebar 展开宽度 | 240px（`w-60`）；`fixed left-0 top-14 h-[calc(100vh-56px)] z-20` | +| Sidebar 折叠宽度 | 64px（`w-16`） | +| 内容区偏移 | 展开态 `ml-60`，折叠态 `ml-16`；`transition-[margin] duration-200` | +| 内容区内边距 | `px-6 py-4` | +| 工具栏 Sticky 偏移 | `sticky top-14 z-30`（Topbar 下方紧贴） | + +--- + +### 5.2 顶部导航栏（Topbar） + +#### 5.2.1 结构规范 + +Topbar 分三区：左区（Logo）、中区（主导航）、右区（工具区）。 ``` -[🏢 Fonrey] 展开态 折叠态 -────────────── ────────────── -仪表盘 Dashboard 🏠 -房源管理 ▾ Property 🏘️ - 全部房源 - 二手 & 租赁 - 商铺 / 写字楼 -客源管理 ▾ Client 👤 -楼盘管理 Complex 🏢 -组织人事 ▾ Org 👥 -权限管理 Permission 🔒 -系统设置 ▾ Settings ⚙️ +┌─────────────────────────────────────────────────────────────────────┐ +│ [🏢 Fonrey ▾] 主页 房源 客源 营销 交易 数据 人事 系统 │ +│ [🔍] [🔔2] [?] [WS 王顺▾] │ +└─────────────────────────────────────────────────────────────────────┘ ``` -- 一级菜单：图标（20px） + 文字 + 右侧箭头（有子菜单时） -- 二级菜单：文字缩进 32px，激活态为 `bg-primary-50 text-primary-700 font-medium` + 左侧 2px 主色竖条 -- 折叠态：只显示图标，Hover 时 Tooltip 显示名称 +| 区域 | 内容 | 样式 | +|---|---|---| +| 左区（150px） | Logo 图 + 产品名"Fonrey" | `flex items-center gap-2 px-4 text-base font-semibold text-neutral-900` | +| 中区（flex-1） | 主分类导航 Tab | 见 5.2.2 | +| 右区（auto） | 全局搜索图标 / 消息 / 帮助 / 头像菜单 | `flex items-center gap-1 px-4` | -### 5.3 列表页模板 +#### 5.2.2 主导航 Tab + +主分类（8项）：**主页 / 房源 / 客源 / 营销 / 交易 / 数据 / 人事 / 系统** + +- 每项：`px-3 py-1 text-sm font-medium rounded-md` +- 默认态：`text-neutral-600 hover:bg-neutral-100 hover:text-neutral-800` +- 激活态：`bg-primary-50 text-primary-700` +- 点击切换主分类 → Sidebar 同步切换为该分类的子菜单 + +#### 5.2.3 右区工具 + +| 元素 | 图标 | 说明 | +|---|---|---| +| 全局搜索 | `MagnifyingGlassIcon` 20px | 点击展开全局搜索 Popover（`max-w-lg`） | +| 消息通知 | `BellIcon` 20px + 红点 Badge | 未读数 ≤ 99，超出显示"99+"；点击打开通知 Drawer | +| 帮助 | `QuestionMarkCircleIcon` 20px | 链接到帮助中心或触发 Tour | +| 头像菜单 | 头像（`w-8 h-8 rounded-full`）+ 姓名缩写 | 下拉菜单：个人设置 / 切换角色 / 退出 | + +#### 5.2.4 Topbar HTML 片段 + +```html +
+ +
+ Fonrey + Fonrey +
+ + + + + +
+ + + + + + + + + + +
+ +
+ + 个人设置 + +
+ + 退出登录 + +
+
+
+
+``` + +--- + +### 5.3 侧边栏（Sidebar） + +#### 5.3.1 结构与折叠规范 + +``` +展开态（240px） 折叠态（64px） +┌─────────────────────────┐ ┌──────┐ +│ ▾ 房源管理 │ │ 🏘️ │ ← 一级图标，Hover Tooltip +│ 全部房源 ● │ │──────│ +│ 二手 & 租赁 │ │ 👤 │ +│ 商铺 / 写字楼 │ │ 🏢 │ +│─────────────────────────│ │ ⚙️ │ +│ 客源管理 │ └──────┘ +│ 私客管理 ● │ +│ 公客池 │ +│─────────────────────────│ +│ [← 折叠] │ ← 折叠按钮（固定在 Sidebar 底部） +└─────────────────────────┘ +``` + +- **Sidebar 定位**：`fixed left-0 top-14 h-[calc(100vh-56px)] z-20 overflow-y-auto` +- **展开宽度**：`w-60`（240px）；折叠宽度：`w-16`（64px） +- **Alpine.js 状态**：`x-data="{ collapsed: $persist(false).as('fonrey:sidebar:collapsed') }"`（使用 `@alpinejs/persist` 持久化） +- **内容区联动**：`
` + +#### 5.3.2 菜单层级 + +Sidebar 展示**当前主分类的子菜单**，分为一级菜单和二级菜单（可选）。 + +| 层级 | 样式 | 激活态 | +|---|---|---| +| 一级菜单（有子项） | `flex items-center gap-3 px-3 py-2 text-sm font-medium text-neutral-700 rounded-md hover:bg-neutral-100 cursor-pointer` | `text-neutral-900 bg-neutral-100` | +| 一级菜单（无子项，直链） | 同上 | `bg-primary-50 text-primary-700 font-semibold border-l-2 border-primary-600 rounded-l-none` | +| 二级菜单 | `ml-8 flex items-center gap-2 px-3 py-1.5 text-sm text-neutral-600 rounded-md hover:bg-neutral-100` | `bg-primary-50 text-primary-700 font-medium border-l-2 border-primary-600 rounded-l-none` | +| 分组标题（可选） | `px-3 pt-4 pb-1 text-xs font-semibold text-neutral-400 uppercase tracking-wider` | — | + +#### 5.3.3 折叠态行为 + +- 仅显示一级菜单图标（`w-5 h-5`），居中 `justify-center` +- 文字、箭头、二级菜单全部隐藏（`x-show="!collapsed"`） +- Hover 图标时，右侧弹出 Tooltip：菜单名称（`absolute left-16 ml-1 px-2 py-1 text-xs bg-neutral-900 text-white rounded whitespace-nowrap z-40`） +- 折叠按钮变为展开图标（`ChevronRightIcon`），固定在底部 + +#### 5.3.4 Sidebar HTML 片段 + +```html + + + +
+ {% block content %}{% endblock %} +
+``` + +--- + +### 5.4 列表页模板 适用：房源列表、客源列表、楼盘列表、权限人员列表、组织人员列表等。 @@ -1029,7 +1267,7 @@ Flatpickr 自定义样式覆盖见附录 10.3。 分页栏（共 3629 条 · 1 2 3 … · 20/页 · 跳至） ``` -### 5.4 详情页模板 +### 5.5 详情页模板 适用：房源详情、客源详情、楼盘详情、员工详情。 @@ -1056,7 +1294,7 @@ Flatpickr 自定义样式覆盖见附录 10.3。 - 右侧栏（`w-80`）用于维护度、相关员工等辅助信息；主区 `flex-1` - **编辑入口 = 详情字段旁的"编辑"链接 → 右侧 Drawer 滑入**（遵循"保留上下文"原则） -### 5.5 设置页模板 +### 5.6 设置页模板 适用：系统设置、权限管理、个人设置。 @@ -1081,15 +1319,15 @@ Flatpickr 自定义样式覆盖见附录 10.3。 - 左侧导航支持二级折叠，激活项左侧 2px 主色竖条 - 底部保存按钮 Sticky（编辑态） -### 5.6 登录/认证页 +### 5.7 登录/认证页 独立布局，不使用 Sidebar。居中卡片 `max-w-md`，品牌色背景装饰（左侧 logo + slogan，右侧表单），参考 Salesforce Lightning 登录页密度。 -### 5.7 空状态页（Empty Page） +### 5.8 空状态页（Empty Page） 见 6.3。 -### 5.8 错误页（403/404/500） +### 5.9 错误页（403/404/500） 三视图共享同一模板，仅图案与文案不同。`max-w-md mx-auto text-center` + SVG 插图 + 主按钮"返回首页"+ 次按钮"联系管理员"。 diff --git a/wiki/concepts/AutomationGovernance.md b/wiki/concepts/AutomationGovernance.md new file mode 100644 index 00000000..38c6ee66 --- /dev/null +++ b/wiki/concepts/AutomationGovernance.md @@ -0,0 +1,37 @@ +--- +title: "AutomationGovernance" +type: concept +tags: [] +last_updated: 2026-04-25 +--- + +# AutomationGovernance（自动化治理） + +## Definition +通过决策框架和标准，对业务流程自动化进行事前评估、事中监控和事后审计的完整治理体系。 + +## Core Framework + +### Four Evaluation Dimensions +1. **Time Savings Per Month**（每月时间节省）：节省是否重复发生且数额可观；流程频率是否足以支撑自动化开销 +2. **Data Criticality**（数据关键性）：是否涉及客户/财务/合同/日程记录；数据错误/延迟/重复/缺失的影响是什么 +3. **External Dependency Risk**（外部依赖风险）：链条中涉及多少外部 API/服务；它们是否稳定、有文档、可观测 +4. **Scalability**（可扩展性）：1x 到 100x 时，重试、去重、限流是否仍能正常工作；异常处理在量级下是否可管理 + +### Five Verdicts +| 裁决 | 条件 | +|------|------| +| **APPROVE** | 价值强、风险可控、架构可维护 | +| **APPROVE AS PILOT** | 价值可期但需限制试点范围 | +| **PARTIAL AUTOMATION ONLY** | 仅自动化安全段落，保留人工检查点 | +| **DEFER** | 流程不成熟、价值不明确或依赖不稳定 | +| **REJECT** | 经济价值弱或运营/合规风险不可接受 | + +## Related Concepts +- [[N8nWorkflowStandard]]：n8n 编排工具的标准工作流模板 +- [[DecisionFramework]]：本概念的评估维度体系 +- [[ReliabilityBaseline]]：生产级工作流的可靠性最低要求 +- [[IntegrationGovernance]]：集成接入的治理规范 + +## Sources +- [[automation-governance-architect]]（primary） diff --git a/wiki/concepts/DecisionFramework.md b/wiki/concepts/DecisionFramework.md new file mode 100644 index 00000000..1ed681bb --- /dev/null +++ b/wiki/concepts/DecisionFramework.md @@ -0,0 +1,54 @@ +--- +title: "DecisionFramework" +type: concept +tags: [] +last_updated: 2026-04-25 +--- + +# DecisionFramework（决策框架） + +## Definition +在 [[AutomationGovernance]] 中用于评估自动化请求的四维分析体系，通过结构化打分决定是否推进自动化实施。 + +## Four Evaluation Dimensions + +### 1. Time Savings Per Month（每月时间节省） +- **问题**：节省是否重复发生且数额可观？流程频率是否足以支撑自动化开销？ +- **评估**：月度节省工时 × 平均时薪 × 12 = 年度 ROI + +### 2. Data Criticality（数据关键性） +- **问题**：是否涉及客户、财务、合同或日程记录？错误/延迟/重复/缺失的影响是什么？ +- **评估**：数据错误的潜在业务损失 × 发生概率 = 风险暴露值 + +### 3. External Dependency Risk（外部依赖风险） +- **问题**：链条中涉及多少外部 API/服务？它们是否稳定、有文档、可观测？ +- **评估**：每个外部依赖的 SLA × 失败传播范围 = 系统脆弱性评分 + +### 4. Scalability（可扩展性） +- **问题**：1x 到 100x 时，重试、去重、限流是否仍能正常工作？异常处理在量级下是否可管理？ +- **评估**：峰值负载测试结果 → 是否需要架构调整 + +## Five Verdicts + +| 裁决 | 条件 | 描述 | +|------|------|------| +| **APPROVE** | 强价值 + 可控风险 + 可维护架构 | 直接推进生产实施 | +| **APPROVE AS PILOT** | 价值可期 + 有限试点 | 受控范围内验证后再决策 | +| **PARTIAL AUTOMATION ONLY** | 仅自动化安全段落 | 保留人工检查点，高风险环节人工介入 | +| **DEFER** | 流程不成熟/价值不明/依赖不稳定 | 等待条件成熟 | +| **REJECT** | 经济价值弱或不可接受的运营/合规风险 | 不实施 | + +## Non-Negotiable Rules +- 不得仅因技术可行就批准自动化 +- 不得在未经明确批准的情况下直接修改关键生产流程 +- 简单健壮优于精巧脆弱 +- 每个推荐必须包含降级方案和责任人 +- 无文档和测试证据不得标记为"完成" + +## Related Concepts +- [[AutomationGovernance]]：决策框架所属的治理体系 +- [[ReliabilityBaseline]]：通过评估后必须满足的可靠性标准 +- [[N8nWorkflowStandard]]：批准实施后的标准工作流模板 + +## Sources +- [[automation-governance-architect]]（primary） diff --git a/wiki/concepts/IntegrationGovernance.md b/wiki/concepts/IntegrationGovernance.md new file mode 100644 index 00000000..10c3153a --- /dev/null +++ b/wiki/concepts/IntegrationGovernance.md @@ -0,0 +1,54 @@ +--- +title: "IntegrationGovernance" +type: concept +tags: [] +last_updated: 2026-04-25 +--- + +# IntegrationGovernance（集成治理） + +## Definition +对每个接入系统的角色、权限、数据流向和失败模式进行明确定义的治理规范，确保多系统协作的清晰性和可审计性。 + +## Core Principle +> **"No integration is approved without source-of-truth clarity."** +> （未经明确数据权威来源，不得批准任何集成。） + +## Required Definitions Per Connected System + +| 维度 | 描述 | +|------|------| +| **System Role & Source of Truth** | 该系统在整个数据流中的角色，以及谁是数据的权威来源 | +| **Auth Method & Token Lifecycle** | 认证方式（API Key / OAuth / JWT 等）和令牌刷新策略 | +| **Trigger Model** | 触发方式（WebHook / Polling / Event Bus / Scheduled） | +| **Field Mappings & Transformations** | 输入/输出字段映射及数据转换规则 | +| **Write-back Permissions & Read-only Fields** | 写回权限范围和只读字段清单 | +| **Rate Limits & Failure Modes** | API 速率限制及常见失败场景处理 | +| **Owner & Escalation Path** | 系统负责人及问题升级路径 | + +## Integration Approval Checklist +- [ ] 数据权威来源已明确定义 +- [ ] 认证方式已配置且令牌刷新机制已实现 +- [ ] 触发模型已选定并实现 +- [ ] 字段映射已文档化 +- [ ] 写回权限已获授权方批准 +- [ ] 速率限制和失败模式已评估 +- [ ] 负责人已指定并知晓升级路径 +- [ ] 集成已通过 [[ReliabilityBaseline]] 中的外部依赖失败测试 + +## Re-Audit Triggers（重审计触发条件） +以下任一情况发生时，需重新评估现有集成： +- API 或 Schema 发生变更 +- 错误率显著上升 +- 业务容量大幅增长 +- 合规要求发生变化 +- 反复出现人工修复的情况 + +## Related Concepts +- [[AutomationGovernance]]：集成治理是自动化治理的核心组成部分 +- [[ReliabilityBaseline]]：通过集成治理确保整个系统链路的可靠性 +- [[N8nWorkflowStandard]]：n8n 工作流中的"External Actions"步骤需遵循集成治理规范 +- [[ReAuditTriggers]]：重审计触发条件 + +## Sources +- [[automation-governance-architect]]（primary） diff --git a/wiki/concepts/N8nWorkflowStandard.md b/wiki/concepts/N8nWorkflowStandard.md new file mode 100644 index 00000000..661d8c02 --- /dev/null +++ b/wiki/concepts/N8nWorkflowStandard.md @@ -0,0 +1,43 @@ +--- +title: "N8nWorkflowStandard" +type: concept +tags: [] +last_updated: 2026-04-25 +--- + +# N8nWorkflowStandard（n8n 工作流标准） + +## Definition +n8n 编排的生产级工作流必须遵循的 10 步标准结构，确保每个自动化链路具备完整的可靠性、可审计性和可恢复能力。 + +## Ten-Step Structure + +1. **Trigger**（触发器）：工作流的启动条件（定时/Webhook/API/事件） +2. **Input Validation**（输入验证）：校验触发数据格式和必填字段 +3. **Data Normalization**（数据规范化）：统一字段格式、类型转换 +4. **Business Logic**（业务逻辑）：核心处理步骤 +5. **External Actions**（外部操作）：对外部系统的写操作（API 调用、数据库写入） +6. **Result Validation**（结果验证）：确认外部操作返回符合预期 +7. **Logging / Audit Trail**（日志/审计跟踪）：记录完整执行轨迹 +8. **Error Branch**（错误分支）：异常处理的专门路径 +9. **Fallback / Manual Recovery**（降级/人工恢复）：无法自动恢复时的兜底方案 +10. **Completion / Status Writeback**（完成/状态回写）：更新任务状态并通知相关方 + +## Naming Convention +``` +[ENV]-[SYSTEM]-[PROCESS]-[ACTION]-v[MAJOR.MINOR] +``` +示例：`PROD-CRM-LeadIntake-CreateRecord-v1.0` + +规则： +- Major version：破坏性逻辑变更 +- Minor version：向后兼容改进 +- 禁止模糊命名（"final"/"new test"/"fix2"） + +## Related Concepts +- [[ReliabilityBaseline]]：每个工作流必须包含的可靠性组件 +- [[AutomationGovernance]]：治理框架决定哪些工作流值得实施 +- [[IntegrationGovernance]]：外部系统集成的治理规范 + +## Sources +- [[automation-governance-architect]]（primary） diff --git a/wiki/concepts/ReAuditTriggers.md b/wiki/concepts/ReAuditTriggers.md new file mode 100644 index 00000000..14baeb28 --- /dev/null +++ b/wiki/concepts/ReAuditTriggers.md @@ -0,0 +1,54 @@ +--- +title: "ReAuditTriggers" +type: concept +tags: [] +last_updated: 2026-04-25 +--- + +# ReAuditTriggers（重审计触发条件） + +## Definition +触发现有自动化流程重新审计的事件条件，防止系统在外部环境变化后继续以过时假设运行。 + +## Trigger Conditions + +### 1. API or Schema Changes（API 或 Schema 变更） +外部依赖的 API 版本升级、字段类型变化、必填字段增减等，均可能破坏现有工作流逻辑。 +**行动**：重新验证字段映射、输入验证和错误处理是否仍有效。 + +### 2. Error Rate Increases（错误率上升） +当某工作流的错误率超过基线阈值（如 >1%），可能是： +- 隐性依赖断裂 +- 上游数据质量恶化 +- 限流策略收紧 +**行动**：追踪错误日志，定位根本原因，重新评估风险评分。 + +### 3. Volume Increases Significantly（容量大幅增长） +业务量从 1x 增长到 10x/100x 时，以下假设可能失效： +- 重试次数和退避策略 +- 去重机制的处理能力 +- 外部 API 速率限制 +**行动**：重新执行 [[DecisionFramework]] 的可扩展性评估维度。 + +### 4. Compliance Requirements Change（合规要求变更） +新法规、行业标准或内部政策的出台，可能对数据处理方式提出新要求。 +**行动**：重新评估 [[IntegrationGovernance]] 的合规维度，必要时回退或修改自动化。 + +### 5. Repeated Manual Fixes Appear（反复出现人工修复） +当运维人员反复以手动方式"修复"同一工作流，说明： +- 该工作流的 [[ReliabilityBaseline]] 不满足实际需求 +- 存在未被识别的失败模式 +**行动**：将人工修复步骤文档化，评估是否应纳入自动化，或修改降级路径。 + +## Key Principle +> **Re-audit does not imply automatic production intervention.** +> （重审计不意味着自动进行生产干预——审计结果是决策依据，不是行动本身。） + +## Related Concepts +- [[AutomationGovernance]]：重审计触发条件由治理框架定义 +- [[IntegrationGovernance]]：API 变更和合规变更直接影响集成治理状态 +- [[ReliabilityBaseline]]：错误率上升触发可靠性重新评估 +- [[DecisionFramework]]：容量变化触发可扩展性维度重新打分 + +## Sources +- [[automation-governance-architect]]（primary） diff --git a/wiki/concepts/ReliabilityBaseline.md b/wiki/concepts/ReliabilityBaseline.md new file mode 100644 index 00000000..5a515d5e --- /dev/null +++ b/wiki/concepts/ReliabilityBaseline.md @@ -0,0 +1,61 @@ +--- +title: "ReliabilityBaseline" +type: concept +tags: [] +last_updated: 2026-04-25 +--- + +# ReliabilityBaseline（可靠性基线） + +## Definition +每个重要工作流必须包含的可靠性最低保障组件，确保自动化系统在各种故障场景下仍能正确响应或优雅降级。 + +## Required Components + +### 1. Explicit Error Branches（显式错误分支） +每个工作流必须为每个可能失败的步骤定义明确的错误处理路径，不能依赖隐式或默认行为。 + +### 2. Idempotency / Duplicate Protection（幂等性/重复保护） +当工作流因重试被多次触发时，必须保证最终结果与单次执行一致（相同输入 → 相同输出，无重复副作用）。 + +### 3. Safe Retries with Stop Conditions（带停止条件的安全重试） +- 指数退避（exponential backoff）避免雪崩 +- 最大重试次数限制 +- 永久失败时触发告警并转入人工处理 + +### 4. Timeout Handling（超时处理） +每个外部调用必须设置合理的超时值，超时后触发预设的错误处理逻辑。 + +### 5. Alerting / Notification Behavior（告警/通知行为） +- 成功/失败状态变更必须通知责任人 +- SLA 即将超时前提前预警 +- 关键指标（如错误率）超过阈值时触发告警 + +### 6. Manual Fallback Path（人工降级路径） +当自动恢复失败时，必须有明确的人工操作路径（包含 SOP 文档和联系方式）。 + +## Logging Baseline（最小日志要求） +每个工作流执行必须记录： +1. 工作流名称和版本 +2. 执行时间戳 +3. 源系统 +4. 受影响实体 ID +5. 成功/失败状态 +6. 错误类型和简短原因说明 + +## Testing Baseline（验收测试要求） +生产推荐前必须通过： +1. Happy Path Test（正常路径测试） +2. Invalid Input Test（无效输入测试） +3. External Dependency Failure Test（外部依赖失败测试） +4. Duplicate Event Test（重复事件测试） +5. Fallback / Recovery Test（降级/恢复测试） +6. Scale / Repetition Sanity Check（规模/重复合理性检查） + +## Related Concepts +- [[N8nWorkflowStandard]]：可靠性基线嵌入在工作流的第 7-10 步中 +- [[DecisionFramework]]：通过决策框架评估后才进入可靠性实现阶段 +- [[AutomationGovernance]]：治理体系定义了可靠性基线的强制要求 + +## Sources +- [[automation-governance-architect]]（primary） diff --git a/wiki/index.md b/wiki/index.md index 2e0119b1..865ea14d 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -4,6 +4,10 @@ - [Overview](overview.md) — living synthesis ## Sources +- [2026-04-25] [Product Feedback Synthesizer Agent](sources/product-feedback-synthesizer.md) +- [2026-04-25] [Specialized Developer Advocate](sources/specialized-developer-advocate.md) +- [2026-04-25] [Automation Governance Architect](sources/automation-governance-architect.md) +- [2026-04-25] [Report Distribution Agent](sources/report-distribution-agent.md) - [2026-04-25] [Data Consolidation Agent](sources/data-consolidation-agent.md) - [2026-04-25] [Supply Chain Strategist Agent](sources/supply-chain-strategist.md) - [2026-04-25] [ZK Steward Agent](sources/zk-steward.md) @@ -409,10 +413,6 @@ - [2026-04-20] [product-sprint-prioritizer](sources/product-sprint-prioritizer.md) — (expected: wiki/sources/product-sprint-prioritizer.md — source missing) - [2026-04-20] [product-trend-researcher](sources/product-trend-researcher.md) — (expected: wiki/sources/product-trend-researcher.md — source missing) - [2026-04-20] [product-manager](sources/product-manager.md) — (expected: wiki/sources/product-manager.md — source missing) -- [2026-04-20] [product-feedback-synthesizer](sources/product-feedback-synthesizer.md) — (expected: wiki/sources/product-feedback-synthesizer.md — source missing) -- [2026-04-20] [specialized-developer-advocate](sources/specialized-developer-advocate.md) — (expected: wiki/sources/specialized-developer-advocate.md — source missing) -- [2026-04-20] [report-distribution-agent](sources/report-distribution-agent.md) — (expected: wiki/sources/report-distribution-agent.md — source missing) -- [2026-04-20] [automation-governance-architect](sources/automation-governance-architect.md) — (expected: wiki/sources/automation-governance-architect.md — source missing) - [2026-04-20] [llm-wiki](sources/llm-wiki.md) — (expected: wiki/sources/llm-wiki.md — source missing) - [2026-04-20] [baoyu-skills](sources/baoyu-skills.md) — (expected: wiki/sources/baoyu-skills.md — source missing) - [Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog](sources/Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog.md) — (expected: wiki/sources/Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog.md — source missing) @@ -858,6 +858,7 @@ - [Audit-Trail](concepts/Audit-Trail.md) - [Automated-Health-Logging](concepts/Automated-Health-Logging.md) - [Automated-Security-Audit](concepts/Automated-Security-Audit.md) +- [AutomationGovernance](concepts/AutomationGovernance.md) - [Availability](concepts/Availability.md) - [AWS-Secrets-Manager](concepts/AWS-Secrets-Manager.md) - [AWS-Source-Identity](concepts/AWS-Source-Identity.md) @@ -960,6 +961,7 @@ - [Data-Sovereignty](concepts/Data-Sovereignty.md) - [DBA-Role-Evolution](concepts/DBA-Role-Evolution.md) - [DealHealthScoring](concepts/DealHealthScoring.md) +- [DecisionFramework](concepts/DecisionFramework.md) - [Defense-in-Depth](concepts/Defense-in-Depth.md) - [Defuddle](concepts/Defuddle.md) - [Delegation-Chain](concepts/Delegation-Chain.md) @@ -1083,6 +1085,7 @@ - [Indexing](concepts/Indexing.md) - [Infrastructure-as-Code](concepts/Infrastructure-as-Code.md) - [Innovation-Pipeline](concepts/Innovation-Pipeline.md) +- [IntegrationGovernance](concepts/IntegrationGovernance.md) - [Intent-Classification](concepts/Intent-Classification.md) - [Intentional-Cloud-Strategy](concepts/Intentional-Cloud-Strategy.md) - [Inversion](concepts/Inversion.md) @@ -1152,6 +1155,7 @@ - [Multi-factor-Authentication](concepts/Multi-factor-Authentication.md) - [Multi-Tenancy](concepts/Multi-Tenancy.md) - [Multi-Window-Architecture](concepts/Multi-Window-Architecture.md) +- [N8nWorkflowStandard](concepts/N8nWorkflowStandard.md) - [nas套件管理](concepts/nas套件管理.md) - [National-Annex](concepts/National-Annex.md) - [NegativePromptingLibrary](concepts/NegativePromptingLibrary.md) @@ -1220,6 +1224,7 @@ - [RAG](concepts/RAG.md) - [Reality-Signal](concepts/Reality-Signal.md) - [RealityKit-SwiftUI-Integration](concepts/RealityKit-SwiftUI-Integration.md) +- [ReAuditTriggers](concepts/ReAuditTriggers.md) - [Reciprocal-Rank-Fusion](concepts/Reciprocal-Rank-Fusion.md) - [RecruitmentFunnelAnalyzer](concepts/RecruitmentFunnelAnalyzer.md) - [Recurring-Task](concepts/Recurring-Task.md) @@ -1230,6 +1235,7 @@ - [Reference-Architecture](concepts/Reference-Architecture.md) - [Release-Management](concepts/Release-Management.md) - [Reliability-Engineering](concepts/Reliability-Engineering.md) +- [ReliabilityBaseline](concepts/ReliabilityBaseline.md) - [Remote-SSH](concepts/Remote-SSH.md) - [RemoteDevelopment](concepts/RemoteDevelopment.md) - [RemoteRescuePattern](concepts/RemoteRescuePattern.md) diff --git a/wiki/log.md b/wiki/log.md index b498b198..c8febc4f 100644 --- a/wiki/log.md +++ b/wiki/log.md @@ -1,4 +1,38 @@ -## [2026-04-25] ingest | Data Consolidation Agent +## [2026-04-26] ingest | Product Feedback Synthesizer +- Source file: Agent/agency-agents/product/product-feedback-synthesizer.md +- Status: ✅ 成功摄入 +- Summary: Product Feedback Synthesizer——The Agency Product 部门的用户反馈综合分析专家 Agent，专精于从多渠道（调查/访谈/工单/评论/社交媒体）收集、分析和综合用户反馈，将海量用户声音蒸馏为可量化的产品决策依据。核心能力：NLP 情感分析与满意度建模（RICE/MoSCoW/Kano 优先级框架）、用户旅程映射、流失预测与早期预警系统。核心理念：定性反馈 → 定量优先级 → 数据驱动路线图。成功指标：24h 内处理关键问题、90%+ 主题准确率、85% 综合反馈产生可衡量决策、NPS 提升 10+ 分。 +- Concepts created: 无（NPS/RICE/MoSCoW/Kano/SentimentAnalysis/UserJourneyMapping/ChurnPrediction/VoC/FeedbackLoop 各仅在本文出现 1 次，待后续批次独立创建；已在 Source Page Key Concepts 节以 [[wikilink]] 格式标注） +- Entities created: 无（The Agency 仅在本文出现 1 次，通过 Source Page Key Entities 保留） +- Source page: wiki/sources/product-feedback-synthesizer.md +- Notes: index.md 中原有 "source missing" 占位条目（2026-04-20）已替换为完整条目；overview.md 新增 "### The Agency — Product 部门" 章节并添加 product-feedback-synthesizer 条目置于 Finance 部门之前；与 [[product-sprint-prioritizer]] 存在优先级框架差异（价值优先 vs 资源约束），已记录于 Source Page Contradictions 节。 + +## [2026-04-25] ingest | Specialized Developer Advocate +- Source file: Agent/agency-agents/specialized/specialized-developer-advocate.md +- Status: ✅ 成功摄入 +- Summary: Developer Advocate Agent——The Agency Specialized 部门的开发者关系工程师，通过 DX 工程审计（Time-to-First-Success）、技术内容创作、社区运营（GitHub/Discord/Slack 响应）、产品反馈闭环（Voice of Developer 报告）推动平台采用。核心理念：Authentic 技术参与（"You don't do marketing — you do developer success"）；DX 改善复合效应优于内容发布；AstroTurf 永久性摧毁开发者信任。成功指标：首次成功 ≤15min、GitHub 响应 ≤24h、教程完成率 ≥50%、开发者 NPS ≥8/10。 +- Concepts created: 无（DeveloperExperienceEngineering/TechnicalContentCreation/CommunityBuilding/ProductFeedbackLoop/DeveloperOnboardingAudit 等均在源文档仅出现 1 次，待后续批次独立创建；已在 Source Page Key Concepts 节以 [[wikilink]] 格式标注） +- Entities created: 无（GitHub/StackOverflow/Discord/KubeCon/OpenTelemetry/The Agency 等各仅出现 1 次，通过 Source Page Key Entities 保留） +- Source page: wiki/sources/specialized-developer-advocate.md +- Notes: index.md 中原有 "source missing" 占位条目（2026-04-20）已替换为完整条目；overview.md Specialized 部门新增 Developer Advocate 条目置于 report-distribution-agent 之后；无重大内容冲突，仅与 [[specialized-workflow-architect]] 存在设计哲学层面的潜在张力（DX 质量优先 vs 快速交付），已记录于 Source Page Contradictions 节。 + +## [2026-04-25] ingest | Automation Governance Architect +- Source file: Agent/agency-agents/specialized/automation-governance-architect.md +- Status: ✅ 成功摄入 +- Summary: Automation Governance Architect——企业自动化治理架构师，负责在实施前评估业务自动化的价值、风险和可维护性。基于 n8n 编排标准 + 四维决策框架（时间节省、数据关键性、外部依赖风险、可扩展性），通过 APPROVE/APPROVE AS PILOT/PARTIAL AUTOMATION ONLY/DEFER/REJECT 五种裁决防止低价值或高风险自动化进入生产，同时推动高价值自动化的标准化落地。核心原则：技术可行不等于值得自动化；简单健壮优于精巧脆弱；每个推荐必须包含降级方案和责任人；无文档和测试证据不得标记为完成。 +- Concepts created: AutomationGovernance, DecisionFramework, N8nWorkflowStandard, ReliabilityBaseline, IntegrationGovernance, ReAuditTriggers +- Entities created: 无（n8n 仅出现 1 次，不满足"出现 ≥2 次"条件，通过 Source Page Key Entities 保留） +- Source page: wiki/sources/automation-governance-architect.md +- Notes: index.md 中原有 "source missing" 占位条目（2026-04-20）已替换为完整条目；overview.md compliance-auditor 条目中已引用 [[automation-governance-architect]]，无需额外修订；无重大内容冲突，仅与 [[specialized-workflow-architect]] 存在设计哲学层面的潜在张力（治理优先 vs 快速交付），已记录于 Source Page Contradictions 节。 + +## [2026-04-25] ingest | Report Distribution Agent +- Source file: Agent/agency-agents/specialized/report-distribution-agent.md +- Status: ✅ 成功摄入 +- Summary: Report Distribution Agent——The Agency Specialized 部门的销售报告自动分发 Agent，基于区域路由参数将合并报告精准送达对应业务员和管理层，支撑工作日 8:00 AM 定时日报和周一 7:00 AM 周报分发，99%+ 定时送达率。核心能力：区域路由（业务员仅收到其区域数据）、公司级汇总报告（管理员/经理）、HTML 邮件格式化、SMTP 传输、分发日志审计（sent/failed 状态 + 时间戳）、失败重试 + 容错继续分发。属销售数据管道的分发层，上游对接 Data Consolidation Agent。 +- Concepts created: 无（Territory Routing/SMTP Transport/Audit Trail/Scheduled Distribution 各仅在本文出现 1 次，暂不单独建 Concept 页面；已在 Source Page Key Concepts 节以 [[wikilink]] 格式标注） +- Entities created: 无（STGCRM/Data Consolidation Agent 各仅出现 1 次，通过 Source Page Key Entities 保留） +- Source page: wiki/sources/report-distribution-agent.md +- Notes: index.md 中原有 "source missing" 占位条目（2026-04-20）已替换为完整条目；overview.md Specialized 部门新增 Report Distribution Agent 条目置于 data-consolidation-agent 之后；无内容冲突（与 [[specialized-document-generator]]（文档生成）和 [[data-consolidation-agent]]（数据整合）均为互补关系，无矛盾）。 - Source file: Agent/agency-agents/specialized/data-consolidation-agent.md - Status: ✅ 成功摄入 - Summary: Data Consolidation Agent——The Agency Specialized 部门的销售数据整合专家 Agent，将分散的销售提取数据聚合为实时仪表盘。核心能力：并行多维度查询（地区/代表/管道/时间维度）、实时达成率计算（revenue/quota * 100，处理除零）、MTD/YTD/Year End 多时间视图、< 1 秒加载 + 60 秒自动刷新、零数据不一致保证。 diff --git a/wiki/overview.md b/wiki/overview.md index 48b42f79..b1946a12 100644 --- a/wiki/overview.md +++ b/wiki/overview.md @@ -97,6 +97,11 @@ The Agency 的 Paid Media 部门专注于企业级付费媒体策略与运营， Key concepts: [[PerformanceMax]], [[SmartBidding]], [[AccountArchitecture]], [[TieredCampaignArchitecture]], [[IncrementalityTesting]], [[ConversionActionHierarchy]], [[CustomerMatch]], [[BudgetPacing]], [[ResponsiveSearchAds]], [[AdStrength]], [[CreativeFatigue]], [[HookBodyCTA]], [[MessageMatch]], [[ABTesting]], [[AdExtensions]] +### The Agency — Product 部门 +|The Agency 的 Product 部门涵盖用户反馈分析、趋势研究、产品路线图规划和行为引导等专业 Agent。| + +**[[product-feedback-synthesizer]]**（Product Feedback Synthesizer）：The Agency 产品部门的用户反馈综合分析专家 Agent——专精于从多渠道（调查/访谈/工单/评论/社交媒体）收集、分析和综合用户反馈，将海量用户声音蒸馏为可量化的产品决策依据。核心能力：NLP 情感分析与满意度建模（NPS/CSAT/CES）、RICE/MoSCoW/Kano 多维度优先级框架、用户旅程映射与痛点识别、流失预测与早期预警系统。核心理念：**定性反馈 → 定量优先级 → 数据驱动路线图**。成功指标：24 小时内处理关键问题、90%+ 主题准确率（利益相关者验证）、85% 综合反馈产生可衡量决策、NPS 提升 10+ 分、80% 反馈驱动功能成功率。与 [[product-sprint-prioritizer]]（Sprint 迭代优先级）和 [[product-trend-researcher]]（产品趋势研究）协同，共同构成 The Agency 产品部门的数据驱动决策体系。 + ### The Agency — Finance 部门 |The Agency 的 Finance 部门涵盖自主支付运营、财务分析与合规管理等专业 Agent。| @@ -717,6 +722,10 @@ Key concepts: [[Django ORM]], [[Django REST Framework]], [[Django Admin 定制]] **[[data-consolidation-agent]]**（Data Consolidation Agent）：销售数据整合专家 Agent——The Agency Specialized 部门的战略数据整合专家，将分散的销售提取数据聚合为实时仪表盘。核心理念：**将原始销售指标转化为可操作的实时决策视图**。核心能力：并行多维度查询（地区/代表/管道/时间维度）、实时达成率计算（revenue / quota * 100，处理除零错误）、MTD/YTD/Year End 多时间视图、< 1 秒仪表盘加载 + 60 秒自动刷新。交付物：Dashboard Report（地区业绩摘要 + 代表排名 + 管道快照 + 6 个月趋势 + Top 5 业绩者）和 Territory Report（地区级深度分析，含所有代表指标及最近 50 条历史记录）。关键原则：**始终使用最新数据**（按 type 取最新 metric_date）；**零数据不一致**（明细与汇总视图完全一致）。与 [[sales-data-extraction-agent]]（上游数据提取）和 [[report-distribution-agent]]（下游分发）构成销售数据管道；与 [[sales-pipeline-analyst]] 共享数据源但职责互补（整合 vs 分析）；与 [[sales-coach-agent]] 协同提供 Top 5 业绩者洞察。属 [[Multi-Agent-System-Reliability]] 的数据层实践，为多 Agent 销售系统提供统一数据视图。 +**[[report-distribution-agent]]**（Report Distribution Agent）：销售报告自动分发专家 Agent——The Agency Specialized 部门的报告分发协调专家，基于区域参数将合并报告精准送达对应业务员和管理层。核心理念：**确保正确的报告在正确的时间到达正确的人**。核心原则：区域路由（业务员仅收到其负责区域的数据）、管理层接收公司级汇总报告、每次分发均记录状态和时间戳（sent/failed）、工作日 8:00 AM 定时日报、周一 7:00 AM 周报、失败时记录错误并继续分发。交付物：HTML 格式区域报告（业务员表格）、公司汇总报告（区域对比表格）、分发日志（接收人/区域/状态/时间戳）。关键指标：99%+ 定时送达率、零区域错误分发、失败发送 5 分钟内识别。核心工作流：定时触发→查询区域和代表→生成报告（调用 Data Consolidation Agent）→HTML 格式化→SMTP 发送→分发日志记录→UI 展示历史。与 [[data-consolidation-agent]] 构成数据管道（整合→分发）；与 [[specialized-document-generator]]（文档生成）协同——生成报告的内容由 Document Generator 提供结构，分发层负责路由和传输。属 [[Multi-Agent-System-Reliability]] 的分发层实践。 + +**[[specialized-developer-advocate]]**（Developer Advocate）：开发者关系工程师 Agent——The Agency Specialized 部门的开发者体验与社区运营专家，通过提升 DX、技术内容创作、社区运营将产品与外部开发者紧密连接，最终推动平台采用和商业价值增长。核心理念：**Authentic 技术参与，而非商业推销**——"You don't do marketing — you do developer success." 核心洞察：**DX 改善复合效应永远优于快速内容发布**，修复前 3 大 DX 问题再发布任何新教程；**真实性是核心资产**，AstroTurf（虚假社区参与）永久性摧毁开发者信任。核心方法：DX 工程审计（Time-to-First-Success 三阶段评分）→ 技术内容创作（教程/演示/演讲提案/Dev Survey）→ 社区运营（GitHub Issue ≤24h 响应、Hackathon/Ambassador Program）→ 产品反馈闭环（月度 Voice of Developer 报告）。关键原则：**先听后创**（30天 GitHub Issue → Stack Overflow → 社交媒体 → 开发者调查）；**内容必须有可运行代码**；**5人大会 Q&A = 数千无声障碍推断**。成功指标：首次成功 ≤15min、GitHub 响应 ≤24h、教程完成率 ≥50%、开发者 NPS ≥8/10。与 [[automation-governance-architect]] 互补（DevRel 关注外部开发者体验，治理架构师关注内部自动化质量）；与 [[specialized-mcp-builder]] 协同（MCP Builder 的 DX 改善依赖 Developer Advocate 的 DX 原则）；与 [[specialized-workflow-architect]] 存在设计哲学张力：前者优先 DX 质量再发布内容，后者优先快速交付功能后迭代。属 The Agency Specialized 部门的技术运营方向。 + ## Conflict Areas 1. **Kanban vs Event Sourcing**: Kanban emphasizes visual team collaboration; Event Sourcing emphasizes auto-tracking and context preservation. **[[Project State Management]]**（事件驱动看板替代方案）vs 传统 PM 工具。核心差异：手动拖拽 vs 自然语言输入；静态快照 vs 全历史保留；无上下文 vs 完整决策链。**[[Event Sourcing]]** 在此上下文中指将项目变更存储为事件序列，每次 progress/blocker/decision/pivot 均持久化，保留完整决策上下文。 diff --git a/wiki/sources/automation-governance-architect.md b/wiki/sources/automation-governance-architect.md new file mode 100644 index 00000000..b8be8233 --- /dev/null +++ b/wiki/sources/automation-governance-architect.md @@ -0,0 +1,49 @@ +--- +title: "Automation Governance Architect" +type: source +tags: [] +date: 2026-04-25 +--- + +## Source File +- [[raw/Agent/agency-agents/specialized/automation-governance-architect.md]] + +## Summary（用中文描述） +- 核心主题：企业自动化治理架构师，负责在实施前评估业务自动化的价值、风险和可维护性 +- 问题域：企业级工作流自动化决策、可靠性保障、审计追溯 +- 方法/机制：基于 n8n 的编排标准 + 四维决策框架（时间节省、数据关键性、外部依赖风险、可扩展性） +- 结论/价值：通过治理优先的方式防止低价值或高风险自动化，推动高价值自动化的标准化落地 + +## Key Claims（用中文描述） +- 自动化决策必须基于价值而非技术可行性 +- 每个推荐必须包含降级方案和责任人 +- 生产级工作流必须包含显式错误分支、幂等性保护、安全重试和人工降级路径 +- 命名规范必须包含环境标识和版本号，避免模糊命名 +- 集成治理需明确数据来源权威（Source of Truth），未经明确不得接入 + +## Key Quotes +> "Do not approve automation only because it is technically possible." — 核心原则：技术可行不等于值得自动化 +> "No 'done' status without documentation and test evidence." — 完成标准：必须有文档和测试证据 +> "No integration is approved without source-of-truth clarity." — 集成前提：必须明确数据权威来源 +> "Prefer simple and robust over clever and fragile." — 架构偏好：简单健壮优于精巧脆弱 + +## Key Concepts +- [[AutomationGovernance]]：自动化治理 — 通过决策框架和标准对业务流程自动化进行事前评估、事中监控和事后审计的完整体系 +- [[N8nWorkflowStandard]]：n8n 工作流标准 — 包含触发、验证、规范化、业务逻辑、外部操作、结果验证、日志、错误分支、降级、状态回写10个强制步骤 +- [[DecisionFramework]]：决策框架 — 四维评估体系（时间节省、数据关键性、外部依赖风险、可扩展性），用于对自动化请求给出 APPROVE / APPROVE AS PILOT / PARTIAL AUTOMATION ONLY / DEFER / REJECT 五种裁决 +- [[ReliabilityBaseline]]：可靠性基线 — 每个重要工作流必须包含：错误分支、幂等性/重复保护、安全重试（带停止条件）、超时处理、告警/通知、人工降级路径 +- [[IntegrationGovernance]]：集成治理 — 每个接入系统需定义：角色与数据权威、认证方式、触发模型、字段映射、写回权限、速率限制、失败模式、负责人 +- [[ReAuditTriggers]]：重审计触发条件 — 当 API/Schema 变更、错误率上升、容量大幅增长、合规要求变更、反复出现人工修复时触发自动化重审计 + +## Key Entities +- [[N8n]]：n8n — 自动化治理架构师的首选编排工具，但治理规则本身是平台无关的 + +## Connections +- [[WorkflowArchitect]] ← relates_to ← [[AutomationGovernanceArchitect]]：两者都关注工作流设计与标准化，但 Workflow Architect 偏实现层面，Automation Governance Architect 偏治理决策层面 +- [[ComplianceAuditor]] ← overlaps ← [[AutomationGovernanceArchitect]]：合规审计与自动化治理在数据关键性和合规风险维度存在重叠 + +## Contradictions +- 与 [[WorkflowArchitect]] 可能的冲突： + - 冲突点：对于同一自动化请求，Workflow Architect 可能倾向快速实现，而 Automation Governance Architect 要求充分评估后方可实施 + - 当前观点：治理优先，防止低价值/高风险自动化进入生产 + - 对方观点：快速交付价值，通过迭代完善 diff --git a/wiki/sources/product-feedback-synthesizer.md b/wiki/sources/product-feedback-synthesizer.md new file mode 100644 index 00000000..67049af6 --- /dev/null +++ b/wiki/sources/product-feedback-synthesizer.md @@ -0,0 +1,50 @@ +--- +title: "Product Feedback Synthesizer Agent" +type: source +tags: [] +date: 2026-04-20 +--- + +## Source File +- [[Agent/agency-agents/product/product-feedback-synthesizer.md]] + +## Summary（用中文描述） +- **核心主题**：产品反馈综合分析 Agent，专精于从多渠道收集、分析和综合用户反馈，提取可操作的产品洞察，并将定性反馈转化为定量优先级和战略建议。 +- **问题域**：用户反馈分散（调查/访谈/工单/评论/社交媒体）、情感分析、主题归类、优先级排序、产品路线图决策支持。 +- **方法/机制**：多渠道收集（主动+反应+被动+社区+竞争渠道）→ 数据清洗标准化 → NLP 情感分析 → 主题标签与优先级分类 → 质量保证审查 → 洞察综合（主题分析/统计相关/用户旅程/优先级评分/影响评估）。 +- **结论/价值**：将海量用户声音蒸馏为可量化的产品决策依据，通过 RICE/MoSCoW/Kano 等框架实现数据驱动的路线图优先级排序，目标 85% 综合反馈产生可衡量决策。 + +## Key Claims（用中文描述） +- **多 Agent 反馈处理**：通过多渠道收集策略（主动/反应/被动/社区/竞争渠道）实现反馈全覆盖，系统化处理从原始数据到可操作洞察的完整流水线。 +- **情感与满意度建模**：NLP 情感分析 + NPS/CSAT/CES 评分关联 + 预测建模，实现满意度趋势早期预警（90% 精度检测满意度下降）。 +- **优先级量化框架**：使用 RICE/MoSCoW/Kano 等多标准决策分析框架，将定性反馈转化为可排序的量化优先级。 +- **洞察驱动的商业价值**：目标 85% 综合反馈产生可衡量决策，NPS 提升 10+ 分，80% 反馈驱动功能成功率。 + +## Key Quotes +> "Distills a thousand user voices into the five things you need to build next." — Agent 核心价值主张 + +## Key Concepts +- [[NPS]]：Net Promoter Score，用户推荐意愿度量，与反馈洞察强相关 +- [[RICE]]：Feature request prioritization framework（Reach × Impact × Confidence / Effort） +- [[MoSCoW]]：Must-have / Should-have / Could-have / Won't-have 优先级分类法 +- [[Kano]]：Kano Model，功能满意度与用户愉悦度关系模型 +- [[SentimentAnalysis]]：NLP 情感分析 + 情绪检测 + 满意度评分 +- [[UserJourneyMapping]]：用户旅程映射与痛点识别 +- [[ChurnPrediction]]：基于反馈模式的流失预测与满意度建模 +- [[VoC]]：Voice of Customer，原声客户，verbatim 分析与引语提取 +- [[FeedbackLoop]]：反馈闭环设计与持续改进流程 + +## Key Entities +- [[The-Agency]]：本 Agent 所属的多智能体框架，Product 部门专注于产品驱动的分析与管理 Agent + +## Connections +- [[product-sprint-prioritizer]] ← extends ← [[product-feedback-synthesizer]] +- [[product-trend-researcher]] ← depends_on ← [[product-feedback-synthesizer]] +- [[product-manager]] ← uses ← [[product-feedback-synthesizer]] + +## Contradictions +- 与 [[product-sprint-prioritizer]] 可能存在优先级框架差异： + - 冲突点：Sprint Prioritizer 可能侧重开发资源约束下的短期迭代优先级，Feedback Synthesizer 侧重基于用户价值的长期路线图优先级。 + - 当前观点：Feedback Synthesizer 强调 RICE/Kano 等多维度价值评估应优先于开发约束。 + - 对方观点：Sprint Prioritizer 强调实际开发资源和 Sprint 容量约束才是优先级决策的最终边界。 + - 建议协调：在 Sprint Planning 层面优先使用 Sprint Prioritizer，在产品路线图规划层面优先使用 Feedback Synthesizer，两者互补而非替代。 diff --git a/wiki/sources/report-distribution-agent.md b/wiki/sources/report-distribution-agent.md new file mode 100644 index 00000000..0d175bbd --- /dev/null +++ b/wiki/sources/report-distribution-agent.md @@ -0,0 +1,46 @@ +--- +title: "Report Distribution Agent" +type: source +tags: [] +date: 2026-04-25 +--- + +## Source File +- [[raw/Agent/agency-agents/specialized/report-distribution-agent.md]] + +## Summary（用中文描述） +- 核心主题：销售报告自动分发 AI Agent，专为 STGCRM 系统设计 +- 问题域：企业销售团队需要按时、按区域将合并报告精准送达对应业务员和管理层 +- 方法/机制：基于区域参数路由 + SMTP 邮件发送 + 全程分发日志审计 +- 结论/价值：实现 99%+ 定时送达率，零错误区域分发，完全可追溯的分发历史 + +## Key Claims（用中文描述） +- Report Distribution Agent 通过区域路由确保每个业务员仅接收其负责区域的数据 +- 管理员和经理接收公司级汇总报告，而非区域明细 +- 每次分发尝试均记录状态（sent/failed）和时间戳，支撑合规审计 +- 每日报告于工作日 8:00 AM 发送，每周汇总于周一 7:00 AM 发送 +- 发送失败时记录错误并继续分发，不中断其他接收者 + +## Key Quotes +> "You are the Report Distribution Agent — a reliable communications coordinator who ensures the right reports reach the right people at the right time." — Agent 身份定义 +> "Territory-based routing: reps only receive reports for their assigned territory" — 核心路由规则 +> "Graceful failures: log errors per recipient, continue distributing to others" — 容错设计 + +## Key Concepts +- [[Territory Routing]]：基于销售区域参数进行路由分发，每个业务员仅接收其分配区域的数据报告 +- [[SMTP Transport]]：通过 SMTP 协议传输 HTML 格式邮件报告的底层技术机制 +- [[Audit Trail]]：分发日志记录，含接收人、区域、状态、时间戳，支持合规查询 +- [[Scheduled Distribution]]：定时任务触发机制（工作日 8:00 AM / 周一 7:00 AM），支持手动按需分发 + +## Key Entities +- [[Data Consolidation Agent]]：为 Report Distribution Agent 提供区域报告和公司汇总报告的数据来源 +- [[STGCRM]]：该 Agent 所服务的企业 CRM 系统品牌，提供区域分配数据和邮件路由规则 + +## Connections +- [[Data Consolidation Agent]] ← feeds_data ← [[Report Distribution Agent]] +- [[Report Distribution Agent]] ← distributes_to ← [[Sales Representative]] +- [[Report Distribution Agent]] ← audit_trail ← [[Compliance System]] + +## Contradictions +- 与 [[Sales Data Extraction Agent]]：Sales Data Extraction Agent 负责原始销售数据提取，Report Distribution Agent 负责报告分发；两者在数据管道中为上下游关系，不存在冲突 + diff --git a/wiki/sources/specialized-developer-advocate.md b/wiki/sources/specialized-developer-advocate.md new file mode 100644 index 00000000..5d4a60de --- /dev/null +++ b/wiki/sources/specialized-developer-advocate.md @@ -0,0 +1,58 @@ +--- +title: "Specialized Developer Advocate" +type: source +tags: [agent, specialized, developer-relations, community, developer-experience] +date: 2026-04-20 +--- + +## Source File +- [[Agent/agency-agents/specialized/specialized-developer-advocate.md]] + +## Summary（用中文描述） +- 核心主题：Developer Advocate Agent——The Agency Specialized 部门的开发者关系工程师，通过提升开发者体验（DX）、创建高质量技术内容、建立真实社区联系，将产品与外部开发者紧密连接，最终推动平台采用和商业价值增长。 +- 问题域：开发者关系（DevRel）、开发者体验优化、技术内容营销（区别于传统营销）、社区运营、产品反馈闭环。 +- 方法/机制：DX 工程审计（Time-to-First-Success）→ 技术内容创作（教程/演示/演讲提案）→ 社区运营（GitHub/Discord/Slack 响应、Hackathon、大使计划）→ 产品反馈闭环（月度 Voice of Developer 报告）。 +- 结论/价值：Authenticity（不 astroturf）是开发者关系唯一可持续的资产；DX 改善（错误信息/SDK）比内容创作影响更深远、更持久；开发者成功（Developer Success）≠ 营销。 + +## Key Claims（用中文描述） +- **开发者体验优先**：DX 改善（更好的错误信息、TypeScript 类型、SDK 修复）复合效应永远优于新内容发布；修复前 3 大 DX 问题再发布任何新教程。 +- **真实性是核心资产**：虚假社区参与（AstroTurf）会永久性摧毁开发者信任；保持技术准确性比发布空内容更重要。 +- **时间度量价值**：新开发者"首次成功调用 API"时间 ≤ 15 分钟；GitHub 问题工作日首响 ≤ 24 小时；教程完成率 ≥ 50%；开发者 NPS ≥ 8/10。 +- **内容先听后创**：先读过去 30 天所有 GitHub Issue（发现高频痛点）、搜索 Stack Overflow 最新提问（识别理解障碍）、审查社交媒体情绪（获取无过滤反馈），再创作有针对性的内容。 +- **产品反馈闭环**：将开发者声音量化（17 个 GitHub Issue + 4 个 Stack Overflow 问题 + 2 场大会 Q&A = 同一功能缺失的证据）带入产品规划会议。 + +## Key Quotes +> "You don't do marketing — you do developer success." — 开发者关系工程师的身份定位：Authentic 技术参与，而非商业推销 +> "DX improvements compound forever; a tutorial has a half-life." — DX 改善的持久价值 vs. 内容创作的时间衰减 +> "A tutorial with an active author gets 3x the trust." — 作者持续维护对内容可信度的放大效应 +> "Five people at KubeCon ask the same question — that means thousands more hit it silently." — 大会 Q&A 模式的大规模推断价值 + +## Key Concepts +- [[DeveloperExperienceEngineering]]：审计并改善"首次 API 调用时间"，构建示例应用、启动工具包和代码模板，量化 DX 质量。 +- [[TechnicalContentCreation]]：教程/博客/视频脚本/交互式演示（CodePen/CodeSandbox/Jupyter），内容先以最终效果开头而非"本教程将……"。 +- [[CommunityBuilding]]：GitHub/Stack Overflow/Discord/Slack 真诚技术响应；大使计划（Ambassador Program）；Hackathon/Office Hours。 +- [[ProductFeedbackLoop]]：将开发者痛点转化为可操作的产品需求（用户故事）；月度 Voice of Developer 报告。 +- [[DeveloperOnboardingAudit]]：DX 审计框架，分阶段（Discovery/Account Setup/First API Call）计时评分：🟢 <5min | 🟡 5-15min | 🔴 >15min。 +- [[AmbassadorProgram]]：分层次贡献者认可机制，与社区价值观一致的真实激励。 +- [[ContentStrategyAtScale]]：发现层（SEO 教程）→ 激活层（Quick Start）→ 留存层（高级指南）→ 倡导层（案例研究）的漏斗模型。 +- [[DeveloperNPS]]：开发者净推荐值，季度调查，目标 ≥ 8/10。 + +## Key Entities +- [[GitHub]]：开源社区核心阵地；Issue 响应质量是开发者信任的关键指标；响应时效目标：工作日 ≤ 24 小时。 +- [[StackOverflow]]：开发者问题解答平台；搜索平台名称按最新排序可发现理解障碍点；回答率目标：≥ 90%。 +- [[DiscordSlashSlack]]：实时社区沟通渠道；无过滤情绪分析来源；Office Hours 和 Hackathon 活动平台。 +- [[OpenTelemetry]]：社区健康指标监控（错误率、文档搜索成功率等）框架。 +- [[KubeCon]]：顶级开发者大会；5 人问同一问题 → 数千人无声遇到同样障碍的推断方法论。 + +## Connections +- [[automation-governance-architect]] ← informs ← [[ProductFeedbackLoop]]（产品反馈与治理评审互补） +- [[specialized-mcp-builder]] ← depends_on ← [[DeveloperExperienceEngineering]]（MCP Builder 的 DX 改善依赖开发者体验工程原则） +- [[design-ux-researcher]] ← informs ← [[DeveloperOnboardingAudit]]（UX 研究方法论应用于 DX 审计） +- [[ContentStrategyAtScale]] ← supports ← [[ProductFeedbackLoop]]（内容策略放大产品反馈影响力） +- [[CommunityBuilding]] ← depends_on ← [[DeveloperExperienceEngineering]]（社区健康依赖底层 DX 质量） + +## Contradictions +- 与 [[specialized-workflow-architect]] 存在设计哲学张力： + - 冲突点：快速交付 vs. 质量保障。Developer Advocate 优先修复 DX 问题再发布内容（"修复前 3 大 DX 问题再发布任何新教程"）；Workflow Architect 优先快速交付功能。 + - 当前观点：DX 改善复合效应优于快速内容发布，内容发布前必须有可运行的代码样本。 + - 对方观点：快速迭代需要尽早发布并通过真实用户反馈迭代，内容质量可随时间改进。