@9deok/paperclip-company-document-management

v0.1.3

Published

24 days ago

Paperclip plugin that routes company events to a document-management agent.

0High
0Medium
0Low

9deok

paperclip plugin automation document-management

Paperclip Company Document Management Plugin

Paperclip 회사 이벤트를 Git-backed 지식베이스 관리 작업으로 바꾸는 플러그인입니다.

이 플러그인은 이벤트를 단순히 agent에게 전달하지 않습니다. 이벤트가 발생하면 Paperclip 주변 맥락을 수집하고, 설정된 Git 문서 저장소에 임시 inbox/context 파일을 쓴 뒤, 문서관리 담당자 agent에게 그 파일을 근거로 문서 정리 작업을 맡깁니다.

What It Does

Paperclip core event를 구독합니다.
중복 이벤트를 eventId 기준으로 제거합니다.
이벤트와 관련된 회사/프로젝트/goal/issue/document/comment/agent/run 맥락을 수집합니다.
Git 문서 저장소에 아래 파일을 씁니다.
- paperclip-inbox/YYYY/MM/DD/*.md
- paperclip-context/YYYY/MM/DD/*.json
이 임시 파일들은 기본적으로 Git commit/push하지 않고, .git/info/exclude에 자동 등록해 agent의 실제 문서 commit에 섞이지 않게 합니다.
문서관리 agent에게 Git repo 경로, inbox 파일, context JSON, 추천 문서 영역을 전달합니다.
contextRetentionDays가 지난 임시 inbox/context 파일은 다음 이벤트 처리 때 자동 삭제합니다.

agent는 이 임시 근거 파일을 보고 실제 지식베이스 문서를 docs/company, docs/goals, docs/projects, docs/people, docs/decisions, docs/research, docs/routines 등에 업데이트하고 별도 커밋을 만들면 됩니다.

Captured Event Types

현재 Paperclip plugin API가 공개한 core event 중 문서화 가치가 있는 이벤트를 구독합니다.

company.created
company.updated
project.created
project.updated
project.workspace_created
project.workspace_updated
project.workspace_deleted
issue.updated
issue.comment.created
issue.document.created
issue.document.updated
issue.document.deleted
issue.relations.updated
issue.checked_out
issue.released
issue.assignment_wakeup_requested
agent.created
agent.updated
agent.status_changed
agent.run.started
agent.run.finished
agent.run.failed
agent.run.cancelled
goal.created
goal.updated
approval.created
approval.decided
budget.incident.opened
budget.incident.resolved
cost_event.created
activity.logged

goal.created, goal.updated는 직접 잡습니다.

issue.created는 구독하지 않습니다. 이슈 생성 시점은 보통 작업 시작 전이라 문서화할 확정 정보가 부족하고, 실제 문서 업데이트는 issue.updated, 댓글, 문서 변경, release/check-out 같은 후속 이벤트에서 처리합니다.

문서관리 에이전트 자신을 호출하는 댓글과 assignment wakeup도 중복 실행을 막기 위해 건너뜁니다. 예를 들어 사용자가 댓글에서 문서관리 에이전트를 직접 멘션하면 Paperclip의 기본 호출이 이미 발생하므로, 플러그인이 같은 에이전트를 한 번 더 호출하지 않습니다.

Routine은 현재 Paperclip plugin event type으로 직접 공개되어 있지 않습니다. 대신 routine 실행으로 만들어진 issue의 originKind === "routine_execution"를 보고 routine 실행을 추론합니다. Paperclip 본체가 routine.created, routine.updated, routine.run_triggered를 plugin event로 공개하면 이 플러그인에서 바로 구독 대상으로 추가하면 됩니다.

Context Bundle

이벤트마다 가능한 범위에서 다음 정보를 수집합니다.

company metadata
project metadata and workspaces
goal detail and related issues
issue detail, relation summary, subtree, orchestration summary
issue comments
issue document summaries and selected document bodies
agent profile/status
run-associated issue context for agent.run.*
compact company snapshot: projects, goals, agents

수집 실패는 전체 처리를 실패시키지 않고 collectionErrors에 기록합니다.

Configuration

Paperclip plugin settings 예시입니다.

{
  "enabled": true,
  "defaultDocumentManagerAgentId": "agent-id",
  "companyAgentMap": {
    "company-id": "company-specific-agent-id"
  },
  "documentRepositoryPath": "/srv/company-knowledge-base",
  "documentRepositoryBranch": "main",
  "writeContextFiles": true,
  "contextRetentionDays": 7,
  "documentInboxDirectory": "paperclip-inbox",
  "documentContextDirectory": "paperclip-context",
  "commitGitChanges": false,
  "pushGitChanges": false,
  "gitRemoteName": "origin",
  "requireCleanGitStatus": true,
  "gitAuthorName": "Paperclip Document Manager",
  "gitAuthorEmail": "paperclip-document-manager@localhost",
  "eventTypes": [],
  "ignoreDocumentManagerAuthoredEvents": true,
  "includeCompanySnapshot": true,
  "includeIssueComments": true,
  "includeIssueDocuments": true,
  "includeIssueSubtree": true,
  "includeIssueOrchestration": true,
  "scheduledSnapshotEnabled": false
}

중요한 설정:

documentRepositoryPath: 서버에서 접근 가능한 Git repo 절대 경로
writeContextFiles: 기본 true; agent가 다시 열어볼 수 있는 임시 근거 파일을 씁니다.
contextRetentionDays: 기본 7; 이 기간보다 오래된 임시 inbox/context 파일은 다음 이벤트 때 삭제합니다. 0이면 삭제하지 않습니다.
commitGitChanges: 기본 false; 임시 inbox/context 파일은 보통 커밋하지 않습니다.
requireCleanGitStatus: commitGitChanges가 true일 때만 context commit 전에 dirty repo를 막는 안전장치입니다.
pushGitChanges: 기본 false; 원격 push는 명시적으로 켜야 합니다.
eventTypes: 비워두면 전체 이벤트를 처리하고, 값을 넣으면 allow-list로 제한합니다.
scheduledSnapshotEnabled: 이벤트 누락 보정용 daily snapshot job입니다. 기본은 꺼져 있습니다.

Git Repository Contract

문서 repo는 플러그인 worker 프로세스가 읽고 쓸 수 있어야 합니다.

git init /srv/company-knowledge-base

플러그인은 기본적으로 Paperclip inbox/context 파일을 commit하지 않습니다. 대신 paperclip-inbox/, paperclip-context/를 .git/info/exclude에 등록해 untracked 임시 파일이 agent의 실제 문서 commit에 섞이지 않도록 합니다.

commitGitChanges: true로 바꾸면 플러그인이 임시 inbox/context 파일만 강제로 stage/commit할 수 있습니다. 이 모드는 감사 추적이 필요할 때만 켜는 것을 권장합니다.

문서관리 agent에게는 다음 작업 규칙이 전달됩니다.

inbox/context 파일은 임시 근거 자료입니다. 변경하거나 stage/commit하지 않습니다.
기존 단일 기준 문서를 우선 업데이트합니다.
새 문서는 중복이 없을 때만 만듭니다.
문서 변경이 있으면 agent가 별도 commit을 만듭니다.
문서 변경이 필요 없으면 ignore 이유를 남깁니다.

Development

npm install
npm run typecheck
npm test
npm run build

UI hot reload가 필요하면 다음을 사용합니다.

npm run dev
npm run dev:ui

Install Into Paperclip

Paperclip Plugin Manager의 Install Plugin modal은 npm package name을 입력하는 흐름입니다. 공식 authoring guide도 production 배포물은 npm package 또는 private npm-compatible registry를 권장하고, GitHub repository URL 설치는 first-class workflow가 아니라고 설명합니다.

UI Install From npm

UI 설치를 하려면 먼저 이 repo를 npm package로 publish해야 합니다.

npm install
npm run typecheck
npm test
npm run build
npm run pack:dry-run
npm login
npm publish

npm publish가 아래처럼 실패하면 패키징 문제가 아니라 npm 계정 인증 정책 문제입니다.

E403 Forbidden - Two-factor authentication or granular access token with bypass 2fa enabled is required to publish packages.

처리 방법은 둘 중 하나입니다.

npm 계정에 2FA를 설정한 뒤 다시 publish합니다.
npm 웹사이트에서 write 권한이 있고 Bypass two-factor authentication이 켜진 granular access token을 만든 뒤, Paperclip 배포/CI 환경에서 그 token으로 publish합니다.

publish 후 Paperclip에서 아래 순서로 설치합니다.

Instance Settings -> Plugins -> Install Plugin
npm Package Name에 입력:

@9deok/paperclip-company-document-management

Install
설치 후 plugin settings의 Configuration 탭에서 최소한 아래 두 값을 설정합니다.

{
  "defaultDocumentManagerAgentId": "agent-id",
  "documentRepositoryPath": "/absolute/path/to/company-knowledge-base"
}

defaultDocumentManagerAgentId는 설정 화면의 문서관리 에이전트 드롭다운에서 선택합니다. 드롭다운 옵션에는 agent 이름, 상태, 실제 agent id가 함께 표시됩니다.

documentRepositoryPath는 Paperclip server process가 접근할 수 있는 서버 내부 절대 경로여야 합니다. Docker로 Paperclip을 운영한다면 문서 Git repo를 container에 mount하고, container 안에서 보이는 경로를 설정해야 합니다.

Private Registry

public npm에 올리지 않을 경우 private npm registry를 사용할 수 있습니다. 이때 Paperclip server가 실행되는 환경에 .npmrc/registry token이 있어야 하고, Plugin Manager에는 같은 package name을 입력합니다.

Local Development Install

publish 전 로컬 개발 중에는 플러그인 루트의 절대 경로를 Paperclip에 설치합니다. 현재 UI modal이 local path 옵션을 노출하지 않는 경우 API 설치를 사용합니다.

curl -X POST http://127.0.0.1:3100/api/plugins/install \
  -H "Content-Type: application/json" \
  -d '{"packageName":"/Users/sj/Desktop/9deok/paperclip-company-document-mangement","isLocalPath":true}'

local path 설치도 npm run build가 먼저 끝나 있어야 합니다.

Package Contract

npm package에는 runtime 산출물만 포함합니다.

dist/manifest.js
dist/worker.js
dist/ui/index.js
README.md

prepublishOnly는 publish 전에 typecheck, test, build를 실행하고, prepack은 package tarball 생성 전에 build를 다시 실행합니다.

Verification

테스트는 다음을 확인합니다.

이벤트를 담당 agent에게 전달
Git repo에 임시 inbox/context 파일 작성
임시 inbox/context 파일을 Git commit 대상에서 제외
오래된 임시 inbox/context 파일 자동 삭제
담당 agent가 만든 이벤트 self-loop 방지
agent 미설정 시 skip
같은 eventId 재전달 dedupe