# @happyvertical/smrt-projects 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/smrt-projects/

版本：0\.62\.1
npm 元数据更新时间：2026-11-17T07:54:46.804Z
中文译文更新时间：2026-11-17T10:07:53.571Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/smrt-projects
原文对照：https://npmcn.com/package/%40happyvertical/smrt-projects/?lang=original
项目主页：https://github.com/happyvertical/smrt#readme
源码仓库：https://github.com/happyvertical/smrt

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2 MB，210 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：15 个
- peer 依赖：svelte ^5\.57\.0
- 首次发布：2026-06-23T01:18:43.797Z
- 最新版本发布：2026-11-17T07:54:46.631Z
- 近 30 天下载量：14766（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：365（近 12 个月 365 个）

## 中文简介

SMRT框架的提供者不可知项目管理模式(问题、公关、仓库、项目)

## 安装

```sh
npm install @happyvertical/smrt-projects
```

也可以使用：`pnpm add @happyvertical/smrt-projects`、`yarn add @happyvertical/smrt-projects`、`bun add @happyvertical/smrt-projects`

## README

# @happy垂直/smrt- project

S-m-r-t框架的提供者不可知项目管理模式。 管理寄存器、问题、调取请求和项目板,同时对外部提供者(GitHub、GitLab等)提供同步支持.

## 安装

```bash
pnpm add @happyvertical/smrt-projects @happyvertical/smrt-timesheets
```

时间录入及其商业快照 [`smrt-timesheets`](https://npmcn.com/package/%40happyvertical/timesheets/README.md) (# 3288); smrt-项目再出口 他们。 在 pnpm 下, 声明 `@happyvertical/smrt-timesheets` 直接:CLI's 明显发现只读到顶级软件包,所以没有它 `smrt db:migrate` 编号 : `db:status` 停止规划 `service_time_entries`, (中文(简体) ), `service_charge_snapshots`,以及 `service_compensation_snapshots`他们的老去 `@happyvertical/smrt-projects:*` 类名继续以已贬值的方式解析 别名; 移动源引用到 `@happyvertical/smrt-timesheets:*` (计: `ServiceTimeEntry` 在安装 smrt 支持的应用程序中, 以 `@happyvertical/smrt-support:ServiceTimeEntry`) (中文(简体) ). 见 [服务 TIME MIGARINE.md](https://npmcn.com/package/%40happyvertical/smrt-projects/SERVICE_TIME_MIGRATION.md)。 。 。 .

## 使用量

```typescript
import {
  Repository, RepositoryCollection,
  Issue, IssueCollection,
  PullRequest, PullRequestCollection,
  Project, ProjectCollection
} from '@happyvertical/smrt-projects';

// Track a repository (token resolved from env var at runtime)
const repos = await RepositoryCollection.create({ db });
const repo = await repos.create({
  owner: 'org',
  name: 'my-app',
  providerType: 'github',
  tokenConfigKey: 'GITHUB_TOKEN',
});
await repo.save();

// Sync repository metadata from GitHub
await repo.sync();

// Discover and sync issues
const issues = await repo.getIssues({ state: 'open' });

// Living Spec: AI-synthesize comments into updated issue body
const result = await issue.incorporateFeedback({ apply: true });

// Rollback to original body
await issue.rollback();
```

## API 密码

### 模型

| 导出 | 说明 |
| --- | --- |
| `Repository` | Git 存储器带有提供者集成. 方法: `sync()`, (中文(简体) ), `getIssues()`, (中文(简体) ), `getPullRequests()`, (中文(简体) ), `createIssue()`, (中文(简体) ), `createPullRequest()`, (中文(简体) ), `summarizeActivity()` |
| `ProjectRepository` | 链接 a `Project` (单位:千美元) `Repository` 带有 `role` (单位:千美元)`primary`, (中文(简体) ), `shared-library`, (中文(简体) ), `infrastructure`); 多对多 |
| `Issue` | 问题/清单(STI基础)。 方法: `sync()`, (中文(简体) ), `incorporateFeedback()`, (中文(简体) ), `rollback()`, (中文(简体) ), `suggestLabels()`, (中文(简体) ), `close()`, (中文(简体) ), `addLabels()`, (中文(简体) ), `addComment()` |
| `PullRequest` | 拉出请求(STI subclass of Issue). 方法: `sync()`, (中文(简体) ), `summarize()`, (中文(简体) ), `merge()`, (中文(简体) ), `markReady()`, (中文(简体) ), `convertToDraft()`, (中文(简体) ), `requestReviewers()`, (中文(简体) ), `findLinkedIssue()` |
| `Project` | 项目委员会(GitHub Projects V2)。 方法: `sync()`, (中文(简体) ), `addItem()`, (中文(简体) ), `moveItem()`, (中文(简体) ), `listItems()`, (中文(简体) ), `updateItemStatus()`, (中文(简体) ), `analyzeHealth()` |
| `ProjectQuestion` | 被请求的生命周期为 `open`, (中文(简体) ), `answered`, (中文(简体) ), `deferred`,或 `superseded`。 。 。 . |
| `ProjectDecision` | 拥有者的选择,包括选择、结果和生命周期的理由 `open`, (中文(简体) ), `decided`, (中文(简体) ), `deferred`,或 `superseded`。 。 。 . |
| `ProjectGovernanceEvent` | 与行为者、行动、地位过渡和修订有关的无法改变的问题/决定历史. |
| `Comment` | 对某一问题或公关的评论 `isQuestion()`, (中文(简体) ), `isApproval()`, (中文(简体) ), `requestsChanges()`, (中文(简体) ), `extractActionItems()`, (中文(简体) ), `summarize()`, (中文(简体) ), `getSentiment()` |
| `Label` | 问题标签/标签;可选范围到存放处或存放处 `Project`方法: `isTypeLabel()`, (中文(简体) ), `isPriorityLabel()`, (中文(简体) ), `getCategory()`, (中文(简体) ), `createInRepository()` |

### 收款

| 导出 | 关键方法 |
| --- | --- |
| `RepositoryCollection` | 标准 CRUD |
| `ProjectRepositoryCollection` | `link()`, (中文(简体) ), `unlink()`, (中文(简体) ), `repositoriesOfProject()`, (中文(简体) ), `projectsOfRepository()`, (中文(简体) ), `unassignedRepositories()` |
| `CommentCollection` | 标准CRUD(项目本土问题评论) |
| `IssueCollection` | `discover()`, (中文(简体) ), `findByProject()`, (中文(简体) ), `findByRepository()`, (中文(简体) ), `findOpen()`, (中文(简体) ), `findByLabel()`, (中文(简体) ), `findByAssignee()`, (中文(简体) ), `findNeedingReview()`, (中文(简体) ), `findWithUnincorporatedFeedback()`, (中文(简体) ), `batchSync()` |
| `PullRequestCollection` | `discover()`, (中文(简体) ), `findByRepository()`, (中文(简体) ), `findOpen()`, (中文(简体) ), `batchSync()` |
| `ProjectCollection` | 标准CRUD, `findByTitle()` |
| `ProjectQuestionCollection` | 房客安全项目列表和查询. |
| `ProjectDecisionCollection` | 房客安全项目列表和查询. |
| `ProjectGovernanceEventCollection` | 订出一个问题或决定的历史. |

### 项目问题和决定

`ProjectGovernanceService` 是所有者问题的书写边界 决定。 主机申请通过合格项目记录类型和ID,所以 同一合同可附在供应商支持下 `Project` 在此软件包中 或申请拥有的项目模式。 服务需要租户范围, 信任的演员投影,以及 `expectedRevision` 每一个变异。 仅 ( 二 ) 指定的 所有人 或 经 主机 授权 的 管理人员 可 回答 或 决定 ; 分配、推迟、重新开放和超会务需要管理人员的授权.

记录默认为 `visibility: 'internal'`; 明确选择 `client` 页:1 客户端记录和通过 `{ visibility: 'client' }` 改为 `listForProject`。 。 。 . 主机批准项目访问并剥去私人上下文引用 正在投影客户端视图。 生命周期历史拒绝更新并删除. 指派活动保留 先前和下一个所有者身份,包括明确所有者身份.

问题和决定保留了按类型分类的参考文献, 对话、 资产或 URL 。 它们不能取代事实: 提取 `open_question` 事实可能播种a `ProjectQuestion`但事实来源 答案状态仍然是单独的生命周期.

`ProjectQuestionsAndDecisions` 从 `@happyvertical/smrt-projects/svelte` 进行授权的预测并发出输入的回答/决定回调。 这个 不获取记录或决定申请权限.

`ProjectInterview` (登记档次) `project-interview`是遵循正道的, 一次记录的表面 在同一时间 `ProjectQuestionView` 编号 : `ProjectDecisionView` 预测和 `onanswer` 编号 : `ondecide` 召回电话。 这个 也不获取。 道具 : `questions`, (中文(简体) ), `decisions` (按 质询,每个问题按主机顺序排列), `busy`, (中文(简体) ), `framing` (按记录编号键): `why`, (中文(简体) ), `unblocks` 标签, `recommendedOptionId`, (中文(简体) ), `startIndex` (读一次 挂载; 默认为第一个打开的记录)和 `onadvance`,接收 `ProjectInterviewAdvanceDetail` (单位:千美元)`index`, (中文(简体) ), `total`, (中文(简体) ), `id`, (中文(简体) ), `kind`, (中文(简体) ), `reason`继续 每一个动作使主机能够坚持恢复位置. 建议的备选办法 (单位:千美元)`framing.recommendedOptionId`,否则选项是 `recommended` 已列出 首先但从不预选,而提问选择则保留其他文本框。 这个 仅在主机重交所提交的记录后进行访问 无`open` 状态( 或撤回它) , 因此失败的保存会让个人在上面 问. 跳过继续, 不调用回话; 回覆更早 记录,显示只读记录的答案。 进展表明立场和 已回答的计数;当未打开记录时,则显示完成状态, 否则返回跳过记录的概要。 焦点移动到每个新的 记录的走向。 条目动画仅在浏览器报告否时运行 减动偏好.

### Canonical 项目规格

`ProjectSpecificationService` 每名租户有一个犬科规格 和合格的项目目标。 内容 `cookbook` 验证和标语化 `@happyvertical/smrt-core/cookbook`· ; `getCookbook()` 返回便携式 `Cookbook` 从 `@happyvertical/smrt-types`,包括委员会 `specs` 所需经费. `saveForProject({ ...scope, title, summary, cookbook, expectedRevision, actor })` 需要一个信任的经理演员. `expectedRevision: null` 表示只创建; 更新需要目前观察到的修订。 拒绝验证 `ProjectSpecificationValidationError` (单位:千美元)`status: 400`; 过时修改拒绝 与 `ProjectGovernanceConflictError`。 。 。 .

当项目创建已拥有交易时, 使用 `ProjectSpecificationService.create({ db: tx, transaction: 'caller' })` 这么说 规格随项目回滚。 默认模式拥有其交易. 主动呼叫者租户必须匹配目标;主机创建儿童项目 在保存前输入授权的租户环境.

### 参与者的开发请求

`ParticipantDevelopmentRequestService.create({ db }).submit()` 接受信任的选项 服务器授权的参与者身份、租户/项目、, `requestKey`,类型和 说明。 它记录参与者的出处 一个无效的 `integrationId`· ; 管理下的集成摄入仍需要非空集成ID. 重复 相同的演员/项目/钥匙返回已接受的请求;更改的有效载荷拒绝 与 `ParticipantDevelopmentRequestConflictError`请求和初步历史 共享一项交易。 主办方在调用前强制参与项目 服务并曝光他们自己的安全DTO,从不收藏突变API.

现有数据库必须应用能够放松的生成迁移 `development_requests.integration_id` 改为无效并添加规格, 问题、决定和历史表,然后允许这些表面。 运行 普通显示 `db:migrate` 并核实计划对等;现有管理 请求出处不变. `pnpm --filter @happyvertical/smrt-projects test:postgres` 使用可支配存储器练习所有三个工作流程 PostgreSQL 数据库包装器.

### STI 等级

`PullRequest` 扩展 `Issue` 通过单表继承。 两者共用同一表,受歧视者为: `_meta_type`。拉动请求添加 `headRef`, (中文(简体) ), `baseRef`, (中文(简体) ), `merged`, (中文(简体) ), `draft`, (中文(简体) ), `additions`, (中文(简体) ), `deletions`, (中文(简体) ), `changedFiles`。 。 。 .

### 常数

`PROJECTS_MODULE_META`, (中文(简体) ), `PROJECTS_UI_SLOTS`

### 密钥类型

`RepositoryProviderType` (单位:千美元)`github | gitlab | bitbucket | azure`, (中文(简体) ), `ProjectProviderType` (单位:千美元)`github | jira | linear | zenhub`, (中文(简体) ), `ProjectStatus`, (中文(简体) ), `SyncStatus`, (中文(简体) ), `SyncOptions`, (中文(简体) ), `SearchFilters`, (中文(简体) ), `CreateIssueInput`, (中文(简体) ), `CreatePRInput`, (中文(简体) ), `MergeMethod`, (中文(简体) ), `IncorporateFeedbackOptions`, (中文(简体) ), `IncorporateFeedbackResult`, (中文(简体) ), `ProjectItem`, (中文(简体) ), `ItemFilters`

### 选项类型

`RepositoryOptions`, (中文(简体) ), `IssueOptions`, (中文(简体) ), `PullRequestOptions`, (中文(简体) ), `ProjectOptions`, (中文(简体) ), `CommentOptions`, (中文(简体) ), `LabelOptions`

### 请求范围仓库客户端

`withRepositoryClient(scope, client, callback)` 绑定一个 `IRepository` SDK 软件 客户端到一个同步请求。 内容 `RepositoryClientScope` 必须完全匹配 仓库的供应商、业主、名称、租户和自营 `baseUrl`页:1 不匹配在环境符号解析前抛出 。 未存储客户端 在模式上或坚持,在召回时恢复先前的范围 解决。 在活动中 `TenantContext`租户也必须符合范围 寄存器; 只显示 `withSystemContext()` 授权绕过 请求租户检查.

```typescript
await withRepositoryClient(
  { provider: 'github', owner: 'org', repo: 'my-app', tenantId },
  installationClient,
  () => repository.sync(),
);
```

## 密钥模式

-   **Token 配置引用**: 存储 env var 名称 (`tokenConfigKey: 'GITHUB_TOKEN'`而不是标志本身。 运行时解析自 `process.env` 或者说 `getModuleConfig()`
-   **活谱** (单位:千美元)`incorporateFeedback()`:AI将问题评论综合到更新的正文. 支持预览模式和 `rollback()`
-   **同步节流**: 如果在5分钟内调用, 同步操作跳过( 覆盖到 `{ force: true }`(中文(简体) )
-   **提供者不可知论**: GitHub 第一级, GitLab/Bitbucket/Azure 类型定义. 用途 `@happyvertical/repos` 财务报告和审定财务报表 `@happyvertical/projects` SDK 软件包
-   **可选标签词汇**数字 : `issue.suggestLabels(vocabulary)` 当没有配置词汇表或输入的决定客户端时,保留其自由标签生成。 两者均提供只读数组 `{ name, description? }` 或解析器;每个标签都经过独立评估,只有0.5以上的标签被退回。 明确的空词汇返回 `[]` 没有供应商的电话。 名称准确而体会大小写;词汇条目仅限于64个标签,128个特征名称,以及512个特征描述. 解析器和配置的提供者错误被传播 .
-   **可选情绪决定**数字 : `Comment.getSentiment()` 保持其现有的基因行为,直到输入的决定得到配置。 在没有注册工具的情况下,它向一个三选择决定请求发送了有边框的评论值. 所选择的概率必须是最大大于0.5的独特概率;绑定或低概率的响应,无效的配置的响应,提供者失败拒绝而不是被默默地视为中性. 这是一项路线确定性规则,而不是对质量的索赔进行校正.

## 依赖关系

-   `@happyvertical/smrt-core` -- ORM 和代码生成
-   `@happyvertical/smrt-config` -- 配置装入
-   `@happyvertical/smrt-tenancy` -- 多租户范围界定
-   `@happyvertical/smrt-types` -- 共同类型定义
-   `@happyvertical/repos` -- 仓库提供者 SDK
-   `@happyvertical/projects` - 项目板供应商SDK
-   端点 : `@happyvertical/smrt-svelte`

## 贡献者指南

见 [`AGENTS.md`](https://npmcn.com/package/%40happyvertical/smrt-projects/AGENTS.md) 用于软件包结构、变化、验证、, 和贡献者的指导.

### 结构化项目问题

`ProjectGovernanceService.createQuestion({ ..., options })` 接受可选 单项选择建议`ProjectQuestionOption`: 稳定 `id`, (中文(简体) ), `label`选项 `description`,可选布尔 `recommended`) (中文(简体) ). 建议列报 仅:创建时未打开问题,没有答案或选择. 身份证必须是 独特和不空; `other` (大小写不敏感)是保留且无法写入的. `question.getOptions()` 附录 `{ id: 'other', label: 'Other' }` 改为结构化 问. 选择选项,或提供空阵列,保留已有的 自由文本问题流.

`answerQuestion` 继续需要非空字符串 `answer`. 附加内容 接受可选 `selectedOptionId` 财务报告和审定财务报表 `idempotencyKey`。明确选择 必须与提供的身份证相匹配,包括: `other`; 其它答案需要文本。 主机 将所选标签发送为 `answer` 普通选择和个人的选择 其他文本。 一般情况 `ProjectQuestionsAndDecisions` 构成部分用品 这些值,使用未选择的收音机组,标出建议,并总是 显示其他文本框。 只有明示形式划界案援引 `onanswer`。 。 。 .

现有的自由文本 API 客户端仍然兼容, 包括回答 a 结构问题,没有选择:服务存储答案和 叶子 `selectedOptionId` 空无相. 它从来不从文本中猜测一个选项. 现有 问题和不可改变的历史没有被重写或回填。 新答案 有历史 `getAnswerSelection()` 附有回答文本的快照,观察修订, 提供明确选项 ID/ 标签; 返回旧事件 `null`。 。 。 .

可选的一能键被限定为一个问题. 租户/项目和 当前所有者/管理者的授权,一个相同的演员,回答,选择, 和注释重放,没有新的修订或历史事件. 用不同的输入冲突重用密钥 。 没有钥匙,现有的 预期修正的冲突行为适用。 交易回滚涵盖两者 问题和历史。 东道方保留对受影响任务的责任 在持续和重放后进行校正.

该添加剂合同补充: `question_options` 财务报告和审定财务报表 `selected_option_id` 栏 改为 `project_questions`,以及 `answer_selection` 改为 `project_governance_events`。 。 。 . 消费者必须先进行正常的明快驱动数据库迁移,然后使用 新释放的表面。 它没有引入新的模式或表格.

## 常见问题

### @happyvertical/smrt-projects 是什么？

SMRT框架的提供者不可知项目管理模式\(问题、公关、仓库、项目\)

### 如何安装 @happyvertical/smrt-projects？

在项目目录运行 npm install @happyvertical/smrt-projects，或使用 pnpm add / yarn add / bun add。

### @happyvertical/smrt-projects 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @happyvertical/smrt-projects 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @happyvertical/smrt-projects 可以商用吗？

@happyvertical/smrt-projects 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @happyvertical/smrt-projects 的下载量有多少？

根据 npm 官方下载统计，@happyvertical/smrt-projects 在 2026/10/17 – 2026/11/15 这 30 天内被下载 14,766 次，日均约 492 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @happyvertical/smrt-projects 还在维护吗？

最新版本 0\.62\.1 发布于 2026/11/17（今天）；至今共发布 365 个版本，其中过去 12 个月发布了 365 个；首次发布于 2026/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

