Python 后端读 TS 仓库：暴力语法对照表

// 条件
if (cond) {
  doA()
} else if (other) {
  doB()
} else {
  doC()
}

// 循环：for...of 遍历值（≈ Python 的 for x in list），for...in 遍历 key（少用，行为坑多）
for (const item of items) { ... }

// while 一样
while (cond) { ... }

// interface：描述一个对象"长什么样"，本仓库里最常见的类型声明形式
interface UserMessage {
  readonly id: string
  readonly content: string
  timestamp?: number   // 加 ? 表示这个字段可选
}

// type：类型别名，能表达 interface 表达不了的（联合类型、映射类型等）
type Status = 'pending' | 'running' | 'done' | 'failed'

// 泛型：函数/类型带类型参数，读到尖括号 <T> 就是这个
function first<T>(items: T[]): T | undefined {
  return items[0]
}

type WebFetchBody =
  | { readonly kind: 'html'; readonly content: string }
  | { readonly kind: 'text'; readonly content: string }

function render(body: WebFetchBody) {
  switch (body.kind) {
    case 'html':
      return renderHtml(body.content)
    case 'text':
      return renderText(body.content)
    default:
      return assertNever(body)   // 编译期保证：漏了一个 kind 分支，这里就编译不过
  }
}

const active = users
  .filter(u => u.status === 'running')
  .map(u => u.name)
  .join(', ')   // 相当于 Python 的 ", ".join(...)，但 join 是数组的方法，不是字符串的方法——顺序反过来了

const [a, b] = [1, 2]
const [a, ...rest] = [1, 2, 3]

const d = { x: 1, y: 2 }
const { x, y } = d               // 按 key 名解构，不是按位置
const { x: renamed } = d         // 解构时重命名
const { x, ...restObj } = d      // 剩余属性，对应 Python dict 的 **rest 没有直接等价，这是 TS 侧的写法

const merged = { ...d1, ...d2 }  // 展开合并，跟 Python 的 **d1, **d2 几乎一样
const combined = [...arr1, ...arr2]  // 数组展开，对应 Python 的 [*a, *b]

function connect({ host, port, timeout = 3000 }: { host: string; port: number; timeout?: number }) {
  ...
}
// 调用方看起来就像 Python 的关键字参数
connect({ host: 'localhost', port: 8080 })

// TS —— 具名导入
import { helper } from '@deepseek-ai/dsh-utils'
// 默认导出（本仓库很少用，几乎全是具名导出，别指望到处找 export default）
import helper from './helper.ts'
// 只导类型，编译后会被完全擦除，运行时不存在
import type { Session } from '@deepseek-ai/dsh-session'

export function helper() { ... }
export const CONST = 1
export type { Session }

class Agent {
  readonly name: string
  private readonly session: Session   // private 是编译期检查，真私有用 #

  constructor(name: string, session: Session) {
    this.name = name
    this.session = session
  }

  get sessionId(): string {           // getter，调用方写 agent.sessionId，不加括号
    return this.session.id
  }

  run(): void {
    ...
  }
}

class Inbox {
  constructor(
    private readonly session: Session,
    private readonly notifications: InboxNotifications,
  ) {}   // 空函数体——两个参数已经自动变成 this.session / this.notifications
}

async function loadSession(id: string): Promise<Session> {
  const raw = await fetchRaw(id)
  return parseSession(raw)
}

// 不 await，拿到的是 Promise 对象本身，不是结果——这是新手最容易踩的坑
const p = loadSession(id)        // p 是 Promise<Session>，不是 Session
const session = await loadSession(id)  // 这样才是 Session

ctx.effect(() => {
  const timer = setInterval(tick, 1000)
  return () => clearInterval(timer)   // 这个返回的函数就是清理逻辑，插件卸载时自动调用
}, 'myPlugin.tick()')

ctx.on('some/waterfall/event', (payload, next) => {
  const transformed = doSomething(payload)
  return next(transformed)   // 忘了这行，链条到这里就断了
})

declare const BRAND: unique symbol
type Branded<B extends string> = string & { readonly [BRAND]: B }
type SessionId = Branded<'SessionId'>
// 构造只能在拥有该 id 的包内部做一次强制转换，其他地方拿到的 SessionId
// 不能直接塞一个普通 string 进去，tsc 会拦

/**
 * 增量投影 durable inbox 事件。
 * @param session - 提供事件流的会话。
 * @returns 尚未被消费的用户消息。
 */