docs: update all docs/conventions for stateful sense, remove stale refs
Phase 4 of RFC #308: Stateful Sense refactor. - CLAUDE.md: updated diagram, tables, examples (no more Signal) - Cleaned stale Signal Bus / DrizzleDB / _signals / retention refs across READMEs, .cursor rules, copilot instructions, .knowledge - Removed drizzle-orm from core package.json (no longer used) - Updated pnpm-lock.yaml Refs #308
This commit is contained in:
+26
-23
@@ -8,25 +8,29 @@
|
||||
|
||||
```typescript
|
||||
// ✅ Good
|
||||
type Signal = {
|
||||
senseId: string
|
||||
value: unknown
|
||||
type WorkflowLaunch = {
|
||||
senseName: string
|
||||
workflowName: string
|
||||
ts: number
|
||||
}
|
||||
|
||||
function createSignal(senseId: string, value: unknown): Signal {
|
||||
return { senseId, value, ts: Date.now() }
|
||||
function recordWorkflowLaunch(senseName: string, workflowName: string): WorkflowLaunch {
|
||||
return { senseName, workflowName, ts: Date.now() }
|
||||
}
|
||||
|
||||
// ❌ Bad
|
||||
interface ISignal {
|
||||
senseId: string
|
||||
value: unknown
|
||||
interface IWorkflowLaunch {
|
||||
senseName: string
|
||||
workflowName: string
|
||||
ts: number
|
||||
}
|
||||
|
||||
class Signal implements ISignal {
|
||||
constructor(public senseId: string, public value: unknown, public ts: number) {}
|
||||
class WorkflowLaunch implements IWorkflowLaunch {
|
||||
constructor(
|
||||
public senseName: string,
|
||||
public workflowName: string,
|
||||
public ts: number,
|
||||
) {}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -65,17 +69,16 @@ type SenseConfig = {
|
||||
当多个字段互斥时,用 discriminated union 代替一堆 optional:
|
||||
|
||||
```typescript
|
||||
// ✅ Good — 编译器保证 sense 和 workflow 不会同时出现
|
||||
type ReflexConfig =
|
||||
| { kind: "sense"; sense: string; interval: string | null; on: string[] | null }
|
||||
| { kind: "workflow"; workflow: string; on: string[] | null }
|
||||
// ✅ Good — 编译器保证两种 overflow 形态互斥且字段完整
|
||||
type WorkflowConfig =
|
||||
| { concurrency: number; overflow: "drop" }
|
||||
| { concurrency: number; overflow: "queue"; maxQueue: number }
|
||||
|
||||
// ❌ Bad — sense 和 workflow 都 optional,运行时才知道到底填了哪个
|
||||
type ReflexConfig = {
|
||||
sense?: string;
|
||||
workflow?: string;
|
||||
interval?: string;
|
||||
on?: string[];
|
||||
// ❌ Bad — 字段一堆 optional,运行时才知道到底填了哪种并发策略
|
||||
type WorkflowConfig = {
|
||||
concurrency?: number;
|
||||
overflow?: string;
|
||||
maxQueue?: number;
|
||||
}
|
||||
```
|
||||
|
||||
@@ -103,9 +106,9 @@ export default function startEngine() { ... }
|
||||
|
||||
| 类型 | 风格 | 示例 |
|
||||
|------|------|------|
|
||||
| 文件 | kebab-case | `signal-bus.ts` |
|
||||
| 类型 | PascalCase | `SignalBus` |
|
||||
| 函数/变量 | camelCase | `createSignalBus` |
|
||||
| 文件 | kebab-case | `sense-scheduler.ts` |
|
||||
| 类型 | PascalCase | `SenseScheduler` |
|
||||
| 函数/变量 | camelCase | `createSenseScheduler` |
|
||||
| 常量 | UPPER_SNAKE | `MAX_RETRY_COUNT` |
|
||||
| 泛型参数 | 单字母或描述性 | `T`, `TValue` |
|
||||
|
||||
|
||||
@@ -117,7 +117,7 @@
|
||||
|
||||
| 项目 | 位置 | 说明 | 置信度 | 建议 |
|
||||
|------|------|------|--------|------|
|
||||
| 已更名 API 仍出现在 README | `packages/core/README.md` | 仍描述 `parseSenseWorkflowDirective`、`ParsedSenseWorkflowDirective`、`SenseComputeRoute`;源码已为 `parseWorkflowTrigger` / `routeSenseComputeOutput` / `RoutedSenseOutput` | **高** | **更新文档**(本次分析不改代码,仅记录)。 |
|
||||
| ~~已更名 API 仍出现在 README~~ | `packages/core/README.md` | (已修正)文档与 stateful sense、`parseWorkflowTrigger` 对齐;`routeSenseComputeOutput` 已移除 | — | 关闭 |
|
||||
| Hermes 选项合并注释 | `packages/workflow-utils/src/shared/hermes-agent.ts` | 注释称 absorbed from `hermes-options.ts`,该文件已不存在 | **中** | **清理注释**,避免误导。 |
|
||||
| `KNOWN_AGENT_ADAPTER_IDS` 含 `codex` | `packages/core/src/agent.ts` | 仓内无 `codex` 适配器包;与常量未被引用叠加 | **中** | **对齐产品**:实现适配器或从列表移除。 |
|
||||
|
||||
@@ -130,7 +130,7 @@
|
||||
1. **高优先级调查**: `createEchoAgent` 与 `KNOWN_AGENT_ADAPTER_IDS` — 要么接入运行时,要么删减以免维护假象。
|
||||
2. **API 面收敛**: `parseDurationStringToMs`、`labelSenseTrigger` 若无意对外,可从 `core` 公共导出移除。
|
||||
3. **`workflow-utils`**: 评估 `isDryRun` 删除;`spawnSafe` 等从 `workflow-utils` 再导出是否仍有必要。
|
||||
4. **文档**: 修正 `packages/core/README.md` 中 Sense→Workflow 路由 API 名称。
|
||||
4. ~~**文档**: 修正 `packages/core/README.md` 中 Sense→Workflow 路由 API 名称。~~(已完成)
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user