@downcity/city 1.1.4 → 1.1.5

package/src/types/cli/CliReporter.ts

@@ -1,167 +0,0 @@
-/**
- * CLI Reporter 类型定义。
- *
- * 关键点（中文）
- * - 为 city CLI 的输出排版提供统一的结构化输入。
- * - 所有命令层只描述“要表达什么”，具体排版交给 reporter 模块。
- * - 类型统一放在 `src/types/cli/`，避免格式协议继续散落在命令实现中。
- */
-
-/**
- * CLI 输出区块的语气类型。
- */
-export type CliReportTone =
-  | "accent"
-  | "success"
-  | "info"
-  | "warning"
-  | "error";
-
-/**
- * CLI 输出中的单条键值详情。
- */
-export type CliReportFact = {
-  /**
-   * 当前详情项的标签文本。
-   *
-   * 说明（中文）
-   * - 会作为左侧对齐列展示，例如 `PID`、`Log`、`URL`。
-   * - 建议使用短标签，避免过长导致块体视觉松散。
-   */
-  label: string;
-  /**
-   * 当前详情项的值文本。
-   *
-   * 说明（中文）
-   * - 会原样展示在右侧内容列。
-   * - 调用方应提前完成路径、URL、数字等业务格式化。
-   */
-  value: string;
-};
-
-/**
- * CLI 输出的基础信息区块。
- */
-export type CliReportBlock = {
-  /**
-   * 当前区块的视觉语气。
-   *
-   * 说明（中文）
-   * - 控制前缀符号与颜色。
-   * - 未传时默认使用 `info` 语气。
-   */
-  tone?: CliReportTone;
-  /**
-   * 当前区块的主标题。
-   *
-   * 说明（中文）
-   * - 应直接表达当前步骤结果，例如 `Console started`。
-   * - 保持简短，避免与 facts 重复。
-   */
-  title: string;
-  /**
-   * 当前区块标题右侧的补充摘要。
-   *
-   * 说明（中文）
-   * - 常用于展示数量、动作阶段等短信息，例如 `1 item`、`restarting`。
-   * - 留空时不渲染摘要区域。
-   */
-  summary?: string;
-  /**
-   * 当前区块下方要展示的详情列表。
-   *
-   * 说明（中文）
-   * - 详情会按统一列宽对齐输出。
-   * - 留空或空数组时不渲染详情行。
-   */
-  facts?: CliReportFact[];
-  /**
-   * 当前区块的附注文本。
-   *
-   * 说明（中文）
-   * - 用于补充一句非结构化说明。
-   * - 会以弱化样式展示，避免抢主信息层级。
-   */
-  note?: string;
-};
-
-/**
- * CLI 输出中的分组列表项。
- */
-export type CliReportListItem = {
-  /**
-   * 当前列表项的视觉语气。
-   *
-   * 说明（中文）
-   * - 控制该项前缀符号与颜色。
-   * - 常见于成功/失败混合列表。
-   */
-  tone?: CliReportTone;
-  /**
-   * 当前列表项的主标题。
-   *
-   * 说明（中文）
-   * - 一般展示 agent 名称、服务名或项目名。
-   * - 尽量避免直接塞入大量详情信息。
-   */
-  title: string;
-  /**
-   * 当前列表项的详情列表。
-   *
-   * 说明（中文）
-   * - 与 block facts 语义一致，但缩进层级更深。
-   * - 用于展示 projectRoot、PID、log 等补充信息。
-   */
-  facts?: CliReportFact[];
-};
-
-/**
- * CLI 输出中的列表分组。
- */
-export type CliReportList = {
-  /**
-   * 当前列表分组的视觉语气。
-   *
-   * 说明（中文）
-   * - 控制分组标题前缀符号与颜色。
-   * - 未传时默认使用 `accent` 语气。
-   */
-  tone?: CliReportTone;
-  /**
-   * 当前列表分组的标题。
-   *
-   * 说明（中文）
-   * - 用于概括整个列表，例如 `Managed agents`。
-   */
-  title: string;
-  /**
-   * 当前列表分组的补充摘要。
-   *
-   * 说明（中文）
-   * - 常用于数量或动作状态，例如 `stopping · 2 items`。
-   */
-  summary?: string;
-  /**
-   * 当前分组下的列表项集合。
-   *
-   * 说明（中文）
-   * - 列表项按给定顺序输出。
-   * - 空数组时只展示标题，不展示子项。
-   */
-  items: CliReportListItem[];
-};
-
-/**
- * CLI renderer 的可选渲染控制参数。
- */
-export type CliRenderOptions = {
-  /**
-   * 是否强制启用 ANSI 颜色。
-   *
-   * 说明（中文）
-   * - `true` 时即使在非 TTY 下也会输出颜色。
-   * - `false` 时完全关闭颜色，便于测试断言。
-   * - 不传时沿用 chalk 默认探测行为。
-   */
-  color?: boolean;
-};

package/src/types/cli/ModelManager.ts

@@ -1,139 +0,0 @@
-/**
- * `city model` 交互式 manager 类型。
- *
- * 关键点（中文）
- * - 统一描述交互式模型管理器中的菜单动作与摘要视图。
- * - 避免 CLI 模块内部散落匿名对象类型，保持命令实现可维护。
- */
-
-/**
- * `city model` 根菜单动作。
- */
-export type ModelManagerRootAction =
-  /**
-   * 进入 provider 管理视图。
-   */
-  | "providers"
-  /**
-   * 进入 model 管理视图。
-   */
-  | "models"
-  /**
-   * 直接进入创建流程。
-   */
-  | "create"
-  /**
-   * 退出交互式管理器。
-   */
-  | "exit";
-
-/**
- * provider 详情视图可执行动作。
- */
-export type ModelManagerProviderAction =
-  /**
-   * 查看 provider 详情。
-   */
-  | "details"
-  /**
-   * 测试 provider，并尝试发现远端模型。
-   */
-  | "discover"
-  /**
-   * 返回上一级菜单。
-   */
-  | "back";
-
-/**
- * model 详情视图可执行动作。
- */
-export type ModelManagerModelAction =
-  /**
-   * 查看 model 详情。
-   */
-  | "details"
-  /**
-   * 切换暂停状态。
-   */
-  | "togglePause"
-  /**
-   * 真实调用一次 model 做连通性测试。
-   */
-  | "test"
-  /**
-   * 绑定到某个 agent 项目的 `execution.modelId`。
-   */
-  | "use"
-  /**
-   * 返回上一级菜单。
-   */
-  | "back";
-
-/**
- * provider 列表中的摘要信息。
- */
-export interface ModelManagerProviderSummary {
-  /**
-   * provider 唯一 ID。
-   */
-  id: string;
-
-  /**
-   * provider 类型。
-   */
-  type: string;
-
-  /**
-   * provider 配置的 baseUrl。
-   *
-   * 说明（中文）
-   * - 可能为空，表示使用 provider 默认地址。
-   */
-  baseUrl?: string;
-
-  /**
-   * 当前引用该 provider 的本地 model 数量。
-   */
-  modelCount: number;
-}
-
-/**
- * model 列表中的摘要信息。
- */
-export interface ModelManagerModelSummary {
-  /**
-   * model 唯一 ID。
-   */
-  id: string;
-
-  /**
-   * model 绑定的 provider ID。
-   */
-  providerId: string;
-
-  /**
-   * 上游真实模型名。
-   */
-  name: string;
-
-  /**
-   * 当前 model 是否已暂停。
-   */
-  isPaused: boolean;
-
-  /**
-   * model 的温度参数。
-   *
-   * 说明（中文）
-   * - 未配置时为空。
-   */
-  temperature?: number;
-
-  /**
-   * model 的最大 token 参数。
-   *
-   * 说明（中文）
-   * - 未配置时为空。
-   */
-  maxTokens?: number;
-}

package/src/types/contact/Contact.ts

@@ -1,82 +0,0 @@
-/**
- * contact 核心类型。
- *
- * 关键点（中文）
- * - 一个 contact 表示一个已确认的点对点 agent 关系。
- * - 每个 contact 固定拥有一条长期 chat history，不额外暴露 session 管理概念。
- */
-
-/**
- * contact 当前关系状态。
- */
-export type ContactStatus = "trusted" | "blocked";
-
-/**
- * contact 当前可达方向。
- */
-export type ContactReachability = "inbound" | "outbound" | "bidirectional";
-
-/**
- * agent contact 记录。
- */
-export interface AgentContact {
-  /**
-   * contact 稳定标识。
-   */
-  id: string;
-  /**
-   * 对方 agent 的展示名称。
-   */
-  name: string;
-  /**
-   * 对方 agent 的 HTTP endpoint；仅 inbound contact 可以为空。
-   */
-  endpoint: string | null;
-  /**
-   * 当前 agent 与对方 agent 的可达方向。
-   */
-  reachability: ContactReachability;
-  /**
-   * 当前关系状态。
-   */
-  status: ContactStatus;
-  /**
-   * 本 agent 调用对方时携带的 token；仅 inbound contact 可以为空。
-   */
-  outboundToken: string | null;
-  /**
-   * 对方调用本 agent 时必须携带的 token hash；仅 outbound contact 可以为空。
-   */
-  inboundTokenHash: string | null;
-  /**
-   * contact 创建时间戳。
-   */
-  createdAt: number;
-  /**
-   * 最近一次成功通信时间戳。
-   */
-  lastSeenAt?: number;
-}
-
-/**
- * contact chat 消息角色。
- */
-export type ContactChatMessageRole = "local" | "remote";
-
-/**
- * contact 长期对话历史中的单条消息。
- */
-export interface ContactChatMessage {
-  /**
-   * 消息角色。
-   */
-  role: ContactChatMessageRole;
-  /**
-   * 消息正文。
-   */
-  text: string;
-  /**
-   * 消息创建时间戳。
-   */
-  createdAt: number;
-}

package/src/types/contact/ContactApproval.ts

@@ -1,150 +0,0 @@
-/**
- * contact approve 协议运行时类型。
- *
- * 关键点（中文）
- * - 这里只描述 link approve 状态机需要的输入，不包含具体存储实现。
- * - link approve 是点对点能力码消费流程，token 由协议自动交换。
- */
-
-import type { ContactApproveLinkRequest } from "./ContactLink.js";
-import type { ContactEndpointReachability } from "./ContactEndpoint.js";
-import type { ContactApproveCallbackReason } from "./ContactLink.js";
-
-/**
- * approve 方对“是否提供回连候选”的本地推导结果。
- */
-export interface ContactApproveCallbackDecision {
-  /**
-   * approve 方是否应该把自己的 endpoint/token 作为回连候选发给发起方做 confirm。
-   */
-  callbackOffered: boolean;
-  /**
-   * 本次推导的原因。
-   */
-  reason: ContactApproveCallbackReason;
-  /**
-   * approve 方自己的 endpoint；仅当推导过程解析出了 endpoint 时存在。
-   */
-  endpoint?: string;
-  /**
-   * approve 方 endpoint 的粗粒度可达范围。
-   */
-  requesterReachability: ContactEndpointReachability;
-  /**
-   * link code 中目标 endpoint 的粗粒度可达范围。
-   */
-  targetReachability: ContactEndpointReachability;
-}
-
-/**
- * 处理远端 contact link approve 请求的输入。
- */
-export interface ApproveContactLinkRequestInput {
-  /**
-   * 当前 agent 项目根目录，用于读取 link 记录并保存 contact。
-   */
-  projectRoot: string;
-  /**
-   * 当前 agent 名称，也就是 link 所属方名称。
-   */
-  ownerAgentName: string;
-  /**
-   * 当前 agent 对外 endpoint；当 link 记录不存在时仍会返回该值辅助诊断。
-   */
-  ownerEndpoint: string;
-  /**
-   * approve 方发来的 link id、secret、agent 名称和可选回连信息。
-   */
-  request: ContactApproveLinkRequest;
-  /**
-   * 当前时间戳；测试可注入，生产环境默认使用 Date.now()。
-   */
-  nowMs?: number;
-}
-
-/**
- * 远端 contact confirm 请求。
- */
-export interface ContactConfirmRequest {
-  /**
-   * 被 confirm 的 link id。
-   */
-  linkId: string;
-  /**
-   * link code 中的一次性明文 secret，用于确认请求来自同一个 approve 方。
-   */
-  secret: string;
-  /**
-   * approve 方 agent 名称。
-   */
-  agentName: string;
-  /**
-   * approve 方提供给发起方主动检查的 endpoint。
-   */
-  endpoint: string;
-  /**
-   * 发起方主动调用 approve 方时携带的 token。
-   */
-  tokenForRequester: string;
-}
-
-/**
- * 远端 contact confirm 响应。
- */
-export interface ContactConfirmResponse {
-  /**
-   * confirm 请求是否执行成功。
-   */
-  success: boolean;
-  /**
-   * 发起方 agent 名称。
-   */
-  agentName: string;
-  /**
-   * 发起方是否已确认可以主动回连 approve 方。
-   */
-  confirmed: boolean;
-  /**
-   * confirm 后发起方保存的 contact 方向。
-   */
-  reachability: "inbound" | "bidirectional";
-  /**
-   * confirm 失败原因。
-   */
-  error?: string;
-}
-
-/**
- * 处理远端 contact confirm 请求的输入。
- */
-export interface ConfirmContactLinkRequestInput {
-  /**
-   * 当前 agent 项目根目录，用于读取 link 记录并更新 contact。
-   */
-  projectRoot: string;
-  /**
-   * 当前 agent 名称，也就是 link 所属方名称。
-   */
-  ownerAgentName: string;
-  /**
-   * confirm 方发来的 link id、secret、agent 名称和回连 token。
-   */
-  request: ContactConfirmRequest;
-  /**
-   * 发起方主动 ping approve 方的验证函数；只有验证成功才能升级为 bidirectional。
-   */
-  verifyCallback: (params: {
-    /**
-     * approve 方提供的回连 endpoint。
-     */
-    endpoint: string;
-    /**
-     * 发起方调用 approve 方时携带的 token。
-     */
-    token: string;
-  }) => Promise<boolean>;
-  /**
-   * 当前时间戳；测试可注入，生产环境默认使用 Date.now()。
-   */
-  nowMs?: number;
-}

package/src/types/contact/ContactChat.ts

@@ -1,47 +0,0 @@
-/**
- * contact chat 类型。
- *
- * 关键点（中文）
- * - 一个 contact 固定一条长期 chat history。
- * - 用户不需要主动维护 session id。
- */
-
-/**
- * contact chat 远端消息请求。
- */
-export interface ContactRemoteChatRequest {
-  /**
-   * 发送方 contact id。
-   */
-  senderContactId: string;
-  /**
-   * 消息正文。
-   */
-  message: string;
-  /**
-   * 消息创建时间戳。
-   */
-  createdAt: number;
-}
-
-/**
- * contact chat 响应。
- */
-export interface ContactChatResponse {
-  /**
-   * chat 是否成功。
-   */
-  success: boolean;
-  /**
-   * 对方回复文本。
-   */
-  reply: string;
-  /**
-   * 本地 contact id。
-   */
-  contactId: string;
-  /**
-   * 失败原因。
-   */
-  error?: string;
-}

package/src/types/contact/ContactCheck.ts

@@ -1,67 +0,0 @@
-/**
- * contact check 类型。
- *
- * 关键点（中文）
- * - check 只检测对方 agent 当前是否在线可用。
- * - check 不创建关系，也不写入 inbox。
- */
-
-/**
- * contact ping 响应。
- */
-export interface ContactPingResponse {
-  /**
-   * ping 是否成功。
-   */
-  success: boolean;
-  /**
-   * 对方 agent 名称。
-   */
-  agentName: string;
-  /**
-   * 对方 contact service 是否可用。
-   */
-  service: "contact";
-  /**
-   * token 校验是否通过。
-   */
-  authenticated?: boolean;
-  /**
-   * 失败原因。
-   */
-  error?: string;
-}
-
-/**
- * contact check 结果。
- */
-export interface ContactCheckResult {
-  /**
-   * 检测目标名称或 endpoint。
-   */
-  target: string;
-  /**
-   * 目标 endpoint。
-   */
-  endpoint: string;
-  /**
-   * 目标是否可访问。
-   */
-  reachable: boolean;
-  /**
-   * contact token 是否有效。
-   */
-  authenticated?: boolean;
-  /**
-   * 往返耗时。
-   */
-  latencyMs: number;
-  /**
-   * 对方 agent 名称。
-   */
-  agentName?: string;
-  /**
-   * 失败原因。
-   */
-  error?: string;
-}